1NEWSFEEDS(5)              InterNetNews Documentation              NEWSFEEDS(5)
2
3
4

NAME

6       newsfeeds - Determine where Usenet articles are sent
7

DESCRIPTION

9       The file pathetc/newsfeeds specifies how incoming articles should be
10       distributed to other programs and files on the server.  It is parsed by
11       the InterNetNews server innd(8) when it starts up, or when directed to
12       by ctlinnd(8).  innd doesn't send articles to remote sites itself, so
13       newsfeeds doesn't directly determine which remote news servers articles
14       are sent to.  Instead, it specifies what batch files should be created
15       or which programs should be run (and what information should be sent to
16       them), and then this information is used by programs like innxmit(8)
17       and innfeed(8) to feed articles to remote sites.
18
19       The newsfeeds file isn't used solely to set up feeding accepted
20       articles to remote sites but also to pass them (or bits of information
21       about them) to any local programs or files that want that data.  For
22       example, controlchan(8), a daemon that processes incoming control
23       messages, runs out of newsfeeds, as could a news to mail gateway.
24
25       The file is interpreted as a set of lines, parsed according to the
26       following rules:  If a line ends with a backslash, the backslash, the
27       newline, and any whitespace at the start of the next line is deleted.
28       This is repeated until the entire "logical" line is collected.  If the
29       logical line is blank or starts with a number sign ("#"), it is
30       ignored.
31
32       All other lines are interpreted as feed entries.  An entry should
33       consist of four colon-separated fields; two of the fields may have
34       optional sub-fields, marked off by a slash.  Fields or sub-fields that
35       take multiple parameters should be separated by a comma.  Extra
36       whitespace can cause problems and should be avoided.  Except for the
37       site names, case is significant.  The format of an entry is:
38
39           sitename[/exclude,exclude,...]\
40               :pattern,pattern...[/distribution,distribution...]\
41               :flag,flag...\
42               :parameter
43
44       Each field is described below.
45
46       The sitename is the name of the site to which a news article can be
47       sent.  It is used for writing log entries and for determining if an
48       article should be forwarded to a site.  (A "site" is the generic term
49       for some destination of newsfeed data; it often corresponds to a remote
50       news peer, but doesn't have to.  For example, a local archiving program
51       run from newsfeeds is also a "site".)  If sitename already appears in
52       the article's Path: header, then the article will not be sent to the
53       site.  The name is usually whatever the remote site uses to identify
54       itself in the Path: header, but can be almost any word.
55
56       Be careful, though, to avoid having the sitename accidentally match a
57       Path: header entry unintentionally.  For this reason, special local
58       entries (such as archivers or gateways) should probably end with an
59       exclamation point to make sure that they do not have the same name as
60       any real site.  For example, "gateway" is an obvious name for the local
61       entry that forwards articles out to a mailing list.  If a site with the
62       name "gateway" posts an article, when the local site receives the
63       article it will see the name in the Path and not send the article to
64       its own "gateway" entry.  Since "gateway!" can't appear as an
65       individual Path: entry since "!" is a delimiter in the Path: header,
66       that would be a better thing to use for sitename.
67
68       (Another way to avoid this problem is with the "Ap" flag; see the
69       description below.)
70
71       If an entry has an exclusion sub-field, the article will not be sent to
72       that site if any of exclude appear in the Path: header.  (It's
73       sometimes convenient to have the sitename be an abbreviated form of the
74       name of the remote site, since all the sitenames to which an article is
75       sent are written to the log and using shorter sitenames can therefore
76       improve performance for large servers.  In this case, the Path: header
77       entries of those sites should be given as exclude entries and the "Ap"
78       flag used so that the abbreviated sitename doesn't accidentally match
79       some other Path: header entry.)
80
81       The same sitename can be used more than once and the appropriate action
82       will be taken for each entry that should receive the article, but this
83       is recommended only for program feeds to avoid confusion.  Case is not
84       significant in site names.
85
86       The comma-separated pattern specifies which groups to send to the site;
87       it is interpreted to build a "subscription list" for the site.  The
88       default subscription is to get all groups carried by the server.  It is
89       a uwildmat(3) pattern supporting poison ("@") wildcards; see the
90       uwildmat(3) man page for full details on the pattern matching language.
91       pattern will be matched against every newsgroup carried by the server
92       and all newsgroups that match will be added to the subscription list
93       for the site.
94
95       Normally, a given article (or information about it) is sent to a site
96       if any of the newsgroups to which the article was posted are in that
97       site's subscription list.  If a newsgroup matches a "@" pattern in
98       pattern, then not only is it not added to the subscription list, but
99       any articles crossposted to that newsgroup also will not be sent to
100       that site even if other newsgroups to which it was crossposted are in
101       that site's subscription list.  This is called a poison pattern
102       (because matching groups are "poisoned").
103
104       For example, to receive all comp.* groups, but only comp.sources.unix
105       within the sources newsgroups, the following pattern can be used:
106
107           comp.*,!comp.sources.*,comp.sources.unix
108
109       Note that the trailing ".*" is required; the pattern has to match the
110       whole newsgroup name.  "comp.sources.*" could be written
111       "comp.sources*" and would exclude the newsgroup comp.sources (if it
112       exists) as well as the groups in the comp.sources.* hierarchy, but note
113       that this would also exclude a newsgroup named comp.sources-only
114       (whereas the above pattern would add that group to the site
115       subscription list since it matches "comp.*" and none of the other
116       patterns).
117
118       For another example, to feed alt.* and misc.* to a given site but not
119       any articles posted to alt.binaries.warez (even if they're also
120       crossposted to other alt.* or misc.* groups), the following pattern can
121       be used:
122
123           alt.*,@alt.binaries.warez,misc.*
124
125       Note, however, that if you reversed the "alt.*" and
126       "@alt.binaries.warez" entries, this pattern would be equivalent to
127       "alt.*,misc.*", since the last matching pattern determines whether a
128       given newsgroup matches and the poison logic only applies if the poison
129       entry is the last matching entry.
130
131       Control messages follow slightly different propagation rules than
132       normal articles; see innd(8) for the details.  Note that most
133       subscriptions should have "!junk,!control,!control.*" in their pattern
134       list due to those propagation rules (and since "junk" is a special
135       internal newsgroup; see wanttrash in inn.conf(5) for more details on
136       what it's used for) and that the best way to keep control messages
137       local to a site is with a distribution.
138
139       A subscription can be further modified by specifying distributions that
140       the site should or should not receive.  The default is to send all
141       articles to all sites that subscribe to any of the groups where it has
142       been posted, but if an article has a Distribution: header and any
143       distributions are specified, then they are checked according to the
144       following rules:
145
146       1.  If the Distribution: header matches any of the values in the sub-
147           field, the article is sent.
148
149       2.  If a distribution starts with an exclamation point, and it matches
150           the Distribution: header, the article is not sent.
151
152       3.  If the Distribution: header does not match any distribution in the
153           site's entry and no negations were used, the article is not sent.
154
155       4.  If the Distribution: header does not match any distribution in the
156           site's entry and any distribution started with an exclamation
157           point, the article is sent.
158
159       If an article has more than one distribution specified, then each one
160       is handled according according to the above rules.  If any of the
161       specified distributions indicate that the article should be sent, it
162       is; if none do, it is not sent.  In other words, the rules are used as
163       a logical or.
164
165       It is almost definitely a mistake to have a single feed that specifies
166       distributions that start with an exclamation point along with some that
167       don't.
168
169       Distributions are text words, not patterns; entries like "*" or "all"
170       have no special meaning.
171
172       The flag field is described in "FLAG VALUES".  The interpretation of
173       the parameter field depends on the type of feed and is explained in
174       more detail in "FEED TYPES".  It can be omitted for some types of
175       feeds.
176
177       The site named "ME" is special.  There must be exactly one such entry,
178       and it should be the first entry in the file.  If the "ME" entry has an
179       exclusion sub-field, incoming articles are rejected completely if any
180       of the names specified in that exclusion sub-field appear in their
181       Path: headers.  If the "ME" entry has a subscription list, that list is
182       prepended to the subscription list of all other entries.  For example,
183       "*,!control,!control.*,!junk,!foo.*" could be used to set the default
184       subscription list for all other feeds so that local postings are not
185       propagated unless "foo.*" explicitly appears in the site's subscription
186       list.  This feature tends to be somewhat confusing since the default
187       subscription is prepended and can be overridden by other patterns.
188
189       If the "ME" entry has a distribution sub-field, only articles that
190       match that distribution list are accepted and all other articles with a
191       distribution are rejected.  A common use for this is to put something
192       like "/!local" in the "ME" entry to reject local postings from other
193       misconfigured sites.  The distribution sub-field of "ME" has no effect
194       on the acceptance or rejection of articles that do not have a
195       Distribution header field.
196
197       An empty "ME" entry is possible, in which case no exclusion patterns
198       will be defined.
199
200       Finally, it is also possible to set variables in newsfeeds and use them
201       later in the file.  A line starting with "$" sets a variable.  For
202       example:
203
204           $LOCALGROUPS=local.*,example.*
205           $CONTROLGROUPS=control,control.*
206
207       This sets the variable "LOCALGROUPS" to "local.*,example.*" and the
208       variable "CONTROLGROUPS" to "control,control.*".  They can later be
209       used elsewhere in the file, such as in a site entry like:
210
211           news.example.com:$LOCALGROUPS:Tf,Wnm:
212
213       which is then completely equivalent to:
214
215           news.example.com:local.*,example.*:Tf,Wnm:
216
217       Variables aren't solely simple substitution.  If either "!" or "@"
218       immediately preceds the variable and the value of the variable contains
219       commas, that character will be duplicated before each comma.  This
220       somewhat odd-sounding behavior is designed to make it easier to use
221       variables to construct feed patterns.  The utility becomes more obvious
222       when you observe that the line:
223
224           news.example.net:*,@$LOCALGROUPS,!$CONTROLGROUPS:Tf,Wnm:
225
226       is therefore equivalent to:
227
228           news.example.net:*,@local.*,@example.*,!control,!control.*:Tf,Wnm:
229
230       which (as explained below) excludes all of the groups in $LOCALGROUPS
231       and unwanted control articles from the feed to that site.
232

FLAG VALUES

234       The flags parameter specifies miscellaneous parameters, including the
235       type of feed, what information should be sent to it, and various
236       limitations on what articles should be sent to a site.  They may be
237       specified in any order and should be separated by commas.  Flags that
238       take values should have the value immediately after the flag letter
239       with no whitespace.  The valid flags are:
240
241       < size
242           An article will only be sent to this site if it is less than size
243           bytes long.  The default is no limit.
244
245       > size
246           An article will only be sent to this site if it is greater than
247           size bytes long.  The default is no limit.
248
249       A checks
250           An article will only be sent to this site if it meets the
251           requirements specified in checks, which should be chosen from the
252           following set.  checks can be multiple letters if appropriate.
253           Note that this flag is not effective on funnel targets; it has to
254           be used on every funnel entry (for instance, Af is not effective on
255           the innfeed! funnel target and therefore has to be specified on
256           every funnelled news site).
257
258           c  Exclude all kinds of control messages.
259
260           C  Only send control messages, not regular articles.
261
262           d  Only send articles with a Distribution: header.  Combined with a
263              particular distribution value in the distribution part of the
264              site entry, this can be used to limit articles sent to a site to
265              just those with a particuliar distribution.
266
267           e  Only send articles where every newsgroup listed in the
268              Newsgroups: header exists in the active file.
269
270           f  Don't send articles rejected by filters.  This is only useful
271              when dontrejectfiltered is set to true in inn.conf.  With that
272              variable set, this lets one accept all articles but not
273              propagate filtered ones to some sites.
274
275           j  Propagate articles according to their Newsgroups: header.  This
276              is only useful when wanttrash is set to true in inn.conf.  With
277              that variable set, articles accepted and filed in "junk" (due to
278              wanttrash) are fed to peers based on their subscription pattern
279              applied to the Newsgroups: header as though they were accepted
280              and all those groups were locally carried.  Otherwise, they are
281              propagated to sites that receive the "junk" newsgroup.
282
283              This variable is useful if you want to run INN with a minimal
284              active file and propagate all posts.
285
286           o  Only send articles for which overview data was stored.
287
288           O  Send articles to this site that don't have an Injection-Info: or
289              X-Trace: header, even if the "O" flag is also given.
290
291           p  Only check the exclusions against the Path: header of articles;
292              don't check the site name.  This is useful if your site names
293              aren't the same as the Path: entries added by those remote
294              sites, or for program feeds where the site name is arbitrary and
295              unrelated to the Path: header.
296
297           If both "c" and "C" are given, the last specified one takes
298           precedence.
299
300       B high/low
301           If a site is being fed by a file, channel, or exploder (see below),
302           the server will normally start trying to write the information as
303           soon as possible.  Providing a buffer may give better system
304           performance and help smooth out overall load if a large batch of
305           news comes in.  The value of the this flag should be two numbers
306           separated by a slash.  high specifies the point at which the server
307           can start draining the feed's I/O buffer, and low specifies when to
308           stop writing and begin buffering again; the units are bytes.  The
309           default is to do no buffering, sending output as soon as it is
310           possible to do so.
311
312       C count
313           If this flag is specified, an article will only be sent to this
314           site if the number of groups it is posted to, plus the square of
315           the number of groups followups would appear in, is no more than
316           count.  30 is a good value for this flag, allowing for instance:
317
318           ·  crossposts to only 5 groups when followups aren't set;
319
320           ·  crossposts to up to 26 groups when followups are set to two
321              groups;
322
323           ·  crossposts to up to 29 groups when followups are set to a single
324              group;
325
326           ·  crossposts to up to 30 groups when followups are set to poster.
327
328           Note that if an article does not contain a Followup-To: header
329           field, the number of groups followups would appear in is the number
330           of groups it is posted to.
331
332       F name
333           Specifies the name of the file that should be used if it's
334           necessary to begin spooling for the site (see below).  If name is
335           not an absolute path, it is taken to be relative to pathoutgoing in
336           inn.conf.  If name is a directory, the file togo in that directory
337           will be used as the file name.
338
339       G count
340           If this flag is specified, an article will only be sent to this
341           site if it is posted to no more than count newsgroups.  This has
342           the problem of filtering out many FAQs, as well as newsgroup
343           creation postings and similar administrative announcements.  Either
344           the C flag or the U flag is a better solution.
345
346       H count
347           If this flag is specified, an article will only be sent to this
348           site if it has count or fewer sites in its Path: line.  This flag
349           should only be used as a rough guide because of the loose
350           interpretation of the Path: header; some sites put the poster's
351           name in the header, and some sites that might logically be
352           considered to be one hop become two because they put the posting
353           workstation's name in the header.  The default value for count if
354           not specified is one.  (Also see the O flag, which is sometimes
355           more appropriate for some uses of this flag.)
356
357       I size
358           The flag specifies the size of the internal buffer for a file feed.
359           If there are more file feeds than allowed by the system, they will
360           be buffered internally in least-recently-used order.  If the
361           internal buffer grows bigger then size bytes, however, the data
362           will be written out to the appropriate file.  The default value is
363           16 KB.
364
365       N status
366           Restricts the articles sent to this site to those in newsgroups
367           with the moderation status given by status.  If status is "m", only
368           articles in moderated groups are sent; if status is "u", only
369           articles in unmoderated groups are sent.
370
371       O originator
372           If this flag is specified, an article will only be sent to this
373           site if it contains an Injection-Info: header (or an X-Trace:
374           header if no Injection-Info: header is found) and the first field
375           of this header matches originator.  originator is a uwildmat(3)
376           expression without commas or a list of such expressions, separated
377           by "/".  The article is never sent if the first character of the
378           pattern begins with "@" and the rest of the pattern matches.  One
379           use of this flag is to restrict the feed to locally generated posts
380           by using an originator pattern that matches the Injection-Info:
381           header added by the local server.
382
383       P priority
384           The nice priority that this channel or program feed should receive.
385           This should be a positive number between 0 and 20 and is the
386           priority that the new process will run with.  This flag can be used
387           to raise the priority to normal if you're using the nicekids
388           parameter in inn.conf.
389
390       Q hashfeed
391           Specifies the hashfeed match expression for this site.  It must be
392           in the form "value/mod" or "start-end/mod".  The Message-ID of the
393           article is hashed using MD5, which results in a 128-bit hash.  The
394           lowest 32 bits are then taken by default as the hashfeed value
395           (which is an integer).  If the hashfeed value modulus "mod" plus
396           one equals "value" or is between "start" and "end", the article
397           will be fed to this site.  All these numbers must be integers.
398
399           It is a deterministic way to control the flow of articles and to
400           split a feed.  For instance:
401
402               Q1/2      Feeds about 50% of all articles to this site.
403               Q2/2      Feeds the other 50% of all articles.
404
405           Another example with three sites:
406
407               Q1-3/10   Feeds about 30% of all articles.
408               Q4-5/10   Feeds about 20% of all articles.
409               Q6-10/10  Feeds about 50% of all articles.
410
411           If this flag is specified multiple times, the contents will be
412           logically "OR"ed together (just one match is needed).
413
414           You can use an extended syntax of the form "value/mod_offset" or
415           "start-end/mod_offset".  As MD5 generates a 128-bit return value,
416           it is possible to specify from which byte-offset the 32-bit integer
417           used by hashfeed starts.  The default value for "offset" is "_0"
418           and thirteen overlapping values from "_0" to "_12" can be used.
419           Only up to four totally independent values exist:  "_0", "_4", "_8"
420           and "_12".
421
422           Therefore, it allows generating a second level of deterministic
423           distribution.  Indeed, if a news server is fed "Q1/2", it can go on
424           splitting thanks to "Q1-3/9_4" for instance.  Up to four levels of
425           deterministic distribution can be used.
426
427           The algorithm is compatible with the one used by Diablo 5.1 and up.
428           If you want to use the legacy quickhashing method used by Diablo
429           before 5.1, you can put an "@" sign just after the Q flag (for
430           instance "Q@1-3/10", but the distribution of the messages is not
431           perfect with this legacy method whose use is discouraged and for
432           which offsets cannot be used).
433
434       S size
435           If the amount of data queued for the site gets to be larger than
436           size bytes, the server will switch to spooling, appending to a file
437           specified by the F flag, or pathoutgoing/sitename if F is not
438           specified.  Spooling usually happens only for channel or exploder
439           feeds, when the spawned program isn't keeping up with its input.
440
441       T type
442           This flag specifies the type of feed for this site.  type should be
443           a letter chosen from the following set:
444
445               c        Channel
446               f        File
447               l        Log entry only
448               m        Funnel (multiple entries feed into one)
449               p        Program
450               x        Exploder
451
452           Each feed is described below in "FEED TYPES".  The default is Tf,
453           for a file feed.
454
455       U count
456           If this flag is specified, an article will only be sent to this
457           site if followups to this article would be posted to no more than
458           count newsgroups.  (Also see C for a more complex way of handling
459           this.)
460
461       W items
462           For a file, channel, or exploder feed, this flag controls what
463           information will be sent to this site.  For a program feed, only
464           the asterisk ("*") has any effect.  items should be chosen from the
465           following set:
466
467           b  Size of the article (in wire format, meaning with CRLF at the
468              end of each line, periods doubled at the beginning of lines, and
469              ending in a line with a single period) in bytes.
470
471           e  The time the article will expire as seconds since epoch if it
472              has an Expires: header, 0 otherwise.
473
474           f  The storage API token of the article (the same as "n").  The
475              article can be retrieved given the storage API token by using
476              sm(8).
477
478           g  The newsgroup the article is in; if cross-posted, then the first
479              of the groups to which the article was posted that this site
480              gets.  (The difference from "G" is that this sends the newsgroup
481              to which the article was posted even if it is a control
482              message.)
483
484           h  The history hash key of the article (derived from the message
485              ID).
486
487           m  The message ID of the article.
488
489           n  The storage API token of the article.  The article can be
490              retrieved given the storage API token by using sm(8).
491
492           p  The time the article was posted a seconds since epoch.
493
494           s  The site that fed the article to the server.  This is taken from
495              either the Path: header or the IP address of the sending site
496              depending on the value of logipaddr in inn.conf.  If logipaddr
497              is true and the IP address is 0.0.0.0 (meaning that the article
498              was fed from localhost by a program like rnews(8)), the Path:
499              header value will be sent instead.
500
501           t  The time the article was received as seconds since epoch.
502
503           *  The names of the appropriate funnel entries, or all sites that
504              get the article (see below for more details).
505
506           D  The value of the Distribution: header of the article, or "?" if
507              there is no such header in the article.
508
509           G  Where the article is stored.  If the newsgroup is crossposted,
510              this is generally the first of the groups to which it was posted
511              that this site receives; however, control messages are filed in
512              control or control.*  (which is the difference between this item
513              and "g").
514
515           H  All of the headers, followed by a blank line.  The Xref header
516              will already be present, and a Bytes header containing the
517              article's size in bytes as in the "b" item will be added to the
518              headers.  If used, this should be the only item in the list.
519
520           N  The value of the Newsgroups: header.
521
522           P  The value of the Path: header.
523
524           O  Overview data for the article.
525
526           R  Information needed for replication (the Xref header without the
527              site name).
528
529           More than one letter can be given.  If multiple items are
530           specified, they will be written in the order specified separated by
531           spaces.  ("H" should be the only item if given, but if it's not a
532           newline will be sent before the beginning of the headers.)  The
533           default is Wn.
534
535           The "H" and "O" items are intended for use by programs that create
536           news overview databases or require similar information.  WnteO is
537           the flag to generate input needed by the overchan(8) program.
538
539           The asterisk ("*") has special meaning.  Normally it expands to a
540           space-separated list of all sites that received the current
541           article.  If, however, this site is a target of a funnel feed (in
542           other words, if it is named by other sites which have the Tm flag),
543           then the asterisk expands to the names of the funnel feeds that
544           received the article.  Similarly, if the site is a program feed, an
545           asterisk in the parameter field will be expanded into the list of
546           funnel feeds that received the article.  A program feed cannot get
547           the site list unless it is the target of other Tm feeds.
548

FEED TYPES

550       innd provides four basic types of feeds:  log, file, program, and
551       channel.  An exploder is a special type of channel.  In addition,
552       several entries can feed into the same feed; these are funnel feeds,
553       which refer to an entry that is one of the other types.  Funnel feeds
554       are partially described above with the description of the W* flag.  A
555       funnel feed gets every article that would be sent to any of the feeds
556       that funnel into it and normally include the W* flag in their flags so
557       that the program processing that feed knows which sites received which
558       articles.  The most common funnel feed is innfeed(8).
559
560       Note that the term "feed" is technically a misnomer, since the server
561       doesn't transfer articles itself and only writes data to a file,
562       program, or log telling another program to transfer the articles.
563
564       The simplest feed is a log feed (Tl).  Other than a mention in the news
565       log file, pathlog/news, no data is written out.  This is equivalent to
566       a Tf entry writing to /dev/null, except that no file is ever opened.
567       Flushing a log feed does nothing.
568
569       A file feed (Tf) is the next simplest type of feed.  When the site
570       should receive an article, the specified data is written out to the
571       file named by the parameter field.  If parameter is not an absolute
572       path, it is taken to be relative to pathoutgoing in inn.conf.  If
573       parameter is not given, it defaults to pathoutgoing/sitename.  The file
574       name should be unique (two file feeds should not ever point to the same
575       file).
576
577       File feeds are designed for use by external programs that periodically
578       process the written data.  To cooperate with innd properly, such
579       external programs should first rename the batch file and then send a
580       flush command for that site to innd using ctlinnd(8).  innd will then
581       write out any buffered data, close the file, and reopen it (under the
582       original name), and the program can process the data in the renamed
583       file at its leisure.  File feeds are most frequently used in
584       combination with nntpsend(8).
585
586       A program feed (Tp) spawns a given program for every article that the
587       site receives.  The parameter field must be the command line to
588       execute, and should contain one instance of %s, which will be replaced
589       by the storage API token of the article (the actual article can be
590       retrieved by the program using sm(8)).  The program will not receive
591       anything on standard input (unlike earlier versions of INN, where the
592       article is sent to the program on stdin), and standard output and error
593       from the program will be set to the error log (pathlog/errlog).  innd
594       will try to avoid spawning a shell if the command has no shell meta-
595       characters; this feature can be defeated if necessary for some reason
596       by appending a semi-colon to the end of the command.  The full path
597       name of the program to be run must be specified unless the command will
598       be run by the shell (and it is strongly recommended that the full path
599       name always be specified regardless).
600
601       If a program feed is the target of a funnel, and if W* appears in the
602       flags of the site, a single asterisk may be present in the parameter
603       and will be replaced by a space-separated list of names of the sites
604       feeding into the funnel which received the relevant article.  If the
605       site is not the target of a funnel, or if the W* flag is not used, the
606       asterisk has no special meaning.
607
608       Flushing a program feed does nothing.
609
610       For a channel (Tc) or exploder (Tx) feed, the parameter field again
611       names the process to start.  As with program feeds, the full path to
612       the program must be specified.  However, rather than spawning the
613       program for every article, it is spawned once and then whenever the
614       site receives an article, the data specified by the site flags is
615       written to the standard input of the spawned program.  Standard output
616       and error are set as with program feeds.  If the process exits, it will
617       be restarted automatically.  If the process cannot be started, the
618       server will spool input to a file named pathoutgoing/sitename and will
619       try to start the process again later.
620
621       When a channel or exploder feed is flushed, the server closes its end
622       of the pipe to the program's standard input.  Any pending data that has
623       not been written will be spooled; see the description of the S flag
624       above.  The server will then spawn a new instance of the program.  No
625       signal is sent to the program; it is up to the program handling a
626       channel or exploder feed to notice end of file on its standard input
627       and exit appropriately.
628
629       Exploders are a special type of channel feed.  In addition to the
630       channel feed behavior described above, exploders can also be sent
631       command lines.  These lines start with an exclamation point and their
632       interpretation is up to the exploder.  The following commands are
633       generated automatically by the server:
634
635           !newgroup group
636           !rmgroup group
637           !flush
638           !flush site
639
640       These commands are sent whenever the ctlinnd(8) command of the same
641       name is received by the server.  In addition, the ctlinnd(8) "send"
642       command can be used to send an arbitrary command line to an exploder.
643       The primary exploder is buffchan(8).
644
645       Finally, Tm feeds are the input to a funnel.  The parameter field of
646       the site should name the site handling articles for all of the funnel
647       inputs.
648

EXAMPLES

650       The syntax of the newsfeeds file is so complex because you can specify
651       a staggering variety of feeds.  INN is capable of interacting with a
652       wide variety of programs that do various things with news articles.
653       Far and away the most common two entries in newsfeeds, however, are
654       file feeds for nntpsend(8) and funnel feeds for innfeed(8).
655
656       The former look like this:
657
658           feed.example.com:*,!control,!control.*,!junk:Tf,Wnm:
659
660       which generates a file named pathoutgoing/feed.example.com containing
661       one line per article consisting of the storage API token, a space, and
662       the message ID.
663
664       The latter look like this:
665
666           feed.example.com:*,!control,!control.*,!junk:Tm:innfeed!
667
668       Very similar, except that this is the input to a funnel feed named
669       "innfeed!".  One could also write this as:
670
671           example/feed.example.com:*,!control,!control.*,!junk:Ap,Tm:innfeed!
672
673       (note the Ap so that articles that contain just "example" in the Path:
674       header will still be sent), which is completely equivalent except that
675       this will be logged in pathlog/news as going to the site "example"
676       rather than "feed.example.com".
677
678       The typical feed entry for innfeed(8) is a good example of a channel
679       feed that's the target of various funnel feeds (make sure the path to
680       innfeed is properly set):
681
682           innfeed!:!*:Tc,Wnm*:<pathbin in inn.conf>/innfeed -y
683
684       Note that the pattern for this feed is just "!*" so that it won't
685       receive any articles directly.  The feed should only receive those
686       articles that would go to one of the funnel feeds that are feeding into
687       it.  innfeed(8) will receive one line per article on its standard input
688       containing the storage API token, the message ID, and a space-separated
689       list of sites that should receive that article.
690
691       Here's a more esoteric example of a channel feed:
692
693           watcher!:*:Tc,Wbnm\
694               :exec awk '$1 > 1000000 { print "BIG", $2, $3 }' > /dev/console
695
696       This receives the byte size of each article along with the storage API
697       token and message ID, and prints to the console a line for every
698       article that's over a million bytes.  This is actually rather a strange
699       way to write this since INN can do the size check itself; the following
700       is equivalent:
701
702           watcher!:*:Tc,>1000000,Wbnm\
703               :exec awk '{ print "BIG", $2, $3}' > /dev/console
704
705       Here's a cute, really simple news to mail gateway that also serves as
706       an example of a fairly fancy program feed:
707
708           mailer!:!*:W*,Tp\
709               :sm %s | innmail -s "News article" *
710
711       Remember that %s is replaced by the storage API token, so this
712       retrieves the article and pipes it into innmail (which is safer than
713       programs like Mail(1) because it doesn't parse the body for tilde
714       commands) with a given subject line.  Note the use of "*" in the
715       command line and W* in the flags; this entry is designed to be used as
716       the target of funnel feeds such as:
717
718           peter@example.com:news.software.nntp:Tm:mailer!
719           sue@example.com:news.admin.misc:Tm:mailer!
720
721       Suppose that the server receives an article crossposted between
722       news.admin.misc and news.software.nntp.  The server will notice that
723       the article should be sent to the site "peter@example.com" and the site
724       "bob@example.com", both of which funnel into "mailer!", so it will look
725       at the "mailer!" site and end up executing the command line:
726
727           sm @...@ | innmail -s "News article" peter@example.com sue@example.com
728
729       which will mail the article to both Peter and Sue.
730
731       Finally, another very useful example of a channel feed:  the standard
732       entry for controlchan(8).  Make sure its path is properly set.
733
734           controlchan!\
735               :!*,control,control.*,!control.cancel/!collabra-internal\
736               :AC,Tc,Wnsm:<pathbin in inn.conf>/controlchan
737
738       This program only wants information about articles posted to a control
739       newsgroup other than control.cancel, which due to the sorting of
740       control messages described in innd(8) will send it all control messages
741       except for cancel messages.  In this case, we also exclude any article
742       with a distribution of "collabra-internal".  controlchan gets the
743       storage API token, the name of the sending site (for processing old-
744       style ihave and sendme control messages, be sure to read about
745       logipaddr in controlchan(8)), and the message ID for each article.
746
747       For many other examples, including examples of the special "ME" site
748       entry, see the example newsfeeds file distributed with INN.  Also see
749       the install documentation that comes with INN for information about
750       setting up the standard newsfeeds entries used by most sites.
751

HISTORY

753       Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
754       Reformatted and rewritten in POD by Russ Allbery <eagle@eyrie.org>.
755
756       $Id: newsfeeds.pod 10283 2018-05-14 12:43:05Z iulius $
757

SEE ALSO

759       active(5), buffchan(8), controlchan(8), ctlinnd(8), inn.conf(5),
760       innd(8), innfeed(8), innxmit(8), nntpsend(8), uwildmat(3).
761
762
763
764INN 2.6.3                         2018-05-14                      NEWSFEEDS(5)
Impressum