X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=doc%2Fman%2Fnewsfeeds.5;fp=doc%2Fman%2Fnewsfeeds.5;h=0000000000000000000000000000000000000000;hb=b7a32e2d73e3ab1add8208d3e157f7269a31ef4d;hp=cc75700308485626b8daf8ba4bdd193e2e24d0f5;hpb=ac902a8299ff4469b356836f431ead31c3377377;p=innduct.git diff --git a/doc/man/newsfeeds.5 b/doc/man/newsfeeds.5 deleted file mode 100644 index cc75700..0000000 --- a/doc/man/newsfeeds.5 +++ /dev/null @@ -1,911 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.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 -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. \*(C+ will -.\" give a nicer C++. Capital omega is used to do unbreakable dashes and -.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, -.\" nothing in troff, for use with C<>. -.tr \(*W- -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "NEWSFEEDS 5" -.TH NEWSFEEDS 5 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation" -.SH "NAME" -newsfeeds \- Determine where Usenet articles are sent -.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 \fIinnd\fR\|(8) when it starts up, or when directed to by -\&\fIctlinnd\fR\|(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 \fIinnxmit\fR\|(8) and -\&\fIinnfeed\fR\|(8) to feed articles to remote sites. -.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, \fIcontrolchan\fR\|(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 \*(L"logical\*(R" 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 \*(L"site\*(R" 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 \*(L"site.\*(R") If \fIsitename\fR already appears in -the article's Path: header, then the article will not be sent to the site. -The name is usually whatever the remote site uses to identify itself in -the Path: header, but can be almost any word. -.PP -Be careful, though, to avoid having the \fIsitename\fR accidentally match a -Path: header entry unintentionally. For this reason, special local -entries (such as archivers or gateways) should probably end with an -exclamation point to make sure that they do not have the same name as any -real site. For example, \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 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: -entry since \f(CW\*(C`!\*(C'\fR is a delimiter in the Path: header, 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. (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: -header entries 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: header entry.) -.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 \*(L"subscription list\*(R" for the site. The -default subscription is to get all groups carried by the server. It is a -\&\fIuwildmat\fR\|(3) pattern supporting poison (\f(CW\*(C`@\*(C'\fR) wildcards; see the \fIuwildmat\fR\|(3) -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 a \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 \*(L"poisoned\*(R"). -.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 <@alt.binaries.warez> -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 \fIinnd\fR\|(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 junk is a special internal newsgroup; see -\&\fIwanttrash\fR in \fIinn.conf\fR\|(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 and any -\&\fIdistribution\fRs are specified, then they are checked according to the -following rules: -.IP "1." 4 -If the Distribution: header 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, the article is not sent. -.IP "3." 4 -If the Distribution: header 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 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 \*(L"\s-1FLAG\s0 \s-1VALUES\s0\*(R". The interpretation of -the \fIparameter\fR field depends on the type of feed and is explained in -more detail in \*(L"\s-1FEED\s0 \s-1TYPES\s0\*(R". 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: -headers. 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 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. -.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 1 -\& $LOCALGROUPS=local.*,example.* -.Ve -.PP -This sets the variable \f(CW\*(C`LOCALGROUPS\*(C'\fR to \f(CW\*(C`local.*,example.*\*(C'\fR. This -variable 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 preceeds 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:Tf,Wnm: -.Ve -.PP -is therefore equivalent to: -.PP -.Vb 1 -\& news.example.net:*,@local.*,@example.*:Tf,Wnm: -.Ve -.PP -which (as explained below) excludes all of the groups in \f(CW$LOCALGROUPS\fR 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. -.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. 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 particuliar -distribution. -.IP "e" 3 -.IX Item "e" -Only send articles where every newsgroup listed in the Newsgroups: header -exists in the active file. -.IP "f" 3 -.IX Item "f" -Don't send articles rejected by filters. This is only useful when -\&\fIdontrejectfiltered\fR is set in \fIinn.conf\fR. With that variable set, this -lets one accept all articles but not propagate filtered ones to some -sites. -.IP "o" 3 -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 X\-Trace: header, 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 of articles; don't -check the site name. This is useful if your site names aren't the same as -the Path: entries added by those remote sites, or for program feeds where -the site name is arbitrary and unrelated to the Path: header. -.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 -the 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(CW30\fR is a -good value for this flag, allowing crossposts to up to 29 groups when -followups are set to a single group or poster and only allowing crossposts -to 5 groups when followups aren't set. -.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: line. This flag should only be -used as a rough guide because of the loose interpretation of the Path: -header; some sites put the poster's name in the header, and some sites -that might logically be considered to be one hop become two because they -put the posting workstation's name in the header. The default value for -\&\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 then \fIsize\fR bytes, however, the data will be written out to -the appropriate file. The default value is 16 \s-1KB\s0. -.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 X\-Trace: header and the first field of this header matches -\&\fIoriginator\fR. \fIoriginator\fR is a \fIuwildmat\fR\|(3) 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 -X\-Trace: header 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 \s-1MD5\s0, 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 \s-1MD5\s0 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 to a generate 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. -.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 \*(L"\s-1FEED\s0 \s-1TYPES\s0\*(R". 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 \s-1CRLF\s0 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, \f(CW0\fR otherwise. -.IP "f" 3 -.IX Item "f" -The storage \s-1API\s0 token of the article (the same as \f(CW\*(C`n\*(C'\fR). The article can -be retrieved given the storage \s-1API\s0 token by using \fIsm\fR\|(8). -.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 \s-1ID\s0). -.IP "m" 3 -.IX Item "m" -The message \s-1ID\s0 of the article. -.IP "n" 3 -.IX Item "n" -The storage \s-1API\s0 token of the article. The article can be retrieved given -the storage \s-1API\s0 token by using \fIsm\fR\|(8). -.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 or the \s-1IP\s0 address of the sending site depending on the -value of \fIlogipaddr\fR in \fIinn.conf\fR. If \fIlogipaddr\fR is true and the \s-1IP\s0 -address is \f(CW0.0.0.0\fR (meaning that the article was fed from localhost by -a program like \fIrnews\fR\|(8)), the Path: header value 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 value of the Distribution: header of the article, or \f(CW\*(C`?\*(C'\fR if there is -no such header 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 will -already be present, and a Bytes header 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 value of the Newsgroups: header. -.IP "P" 3 -.IX Item "P" -The value of the Path: header. -.IP "O" 3 -.IX Item "O" -Overview data for the article. -.IP "R" 3 -.IX Item "R" -Information needed for replication (the Xref header 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 \fIoverchan\fR\|(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 \fIinnfeed\fR\|(8). -.PP -Note that the term \*(L"feed\*(R" 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 \fIctlinnd\fR\|(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 -\&\fInntpsend\fR\|(8). -.PP -A program feed (\fBTp\fR) spawns a given program for every article that the -site receives. The \fIparamter\fR field must be the command line to execute, -and should contain one instance of \f(CW%s\fR, which will be replaced by the -storage \s-1API\s0 token of the article (the actual article can be retrieved by -the program using \fIsm\fR\|(8)). The program will not receive anything on -standard input (unlike earlier versions of \s-1INN\s0, 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 \fIctlinnd\fR\|(8) command of the same name -is received by the server. In addition, the \fIctlinnd\fR\|(8) \f(CW\*(C`send\*(C'\fR command -can be used to send an arbitrary command line to an exploder. The primary -exploder is \fIbuffchan\fR\|(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" -All of the following examples assume that \s-1INN\s0 was installed with a prefix -of \fI/usr/local/news\fR; if you installed it somewhere else, modify the -paths as appropriate. -.PP -The syntax of the \fInewsfeeds\fR file is so complex because you can specify -a staggering variety of feeds. \s-1INN\s0 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 \fInntpsend\fR\|(8) and funnel feeds for \fIinnfeed\fR\|(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 \s-1API\s0 token, a space, and the -message \s-1ID\s0. -.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 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 \fIinnfeed\fR\|(8) is a good example of a channel feed -that's the target of various funnel feeds: -.PP -.Vb 1 -\& innfeed!:!*:Tc,Wnm*:/usr/local/news/bin/startinnfeed \-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. \fIinnfeed\fR\|(8) (spawned by \fBstartinnfeed\fR) will receive one line per -article on its standard input containing the storage \s-1API\s0 token, the -message \s-1ID\s0, 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 2 -\& watcher!:*:Tc,Wbnm\e -\& :exec awk '$1 > 1000000 { print "BIG", $2, $3 }' > /dev/console -.Ve -.PP -This receives the byte size of each article along with the storage \s-1API\s0 -token and message \s-1ID\s0, and prints to the console a line for every article -that's over a million bytes. This is actually rather a strange way to -write this since \s-1INN\s0 can do the size check itself; the following is -equivalent: -.PP -.Vb 2 -\& watcher!:*:Tc,>1000000,Wbnm\e -\& :exec awk '{ print "BIG", $2, $3}' > /dev/console -.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%s\fR is replaced by the storage \s-1API\s0 token, so this -retrieves the article and pipes it into \fBinnmail\fR (which is safer than -programs like \fIMail\fR\|(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 1 -\& sm @...@ | innmail \-s "News article" 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 \fIcontrolchan\fR\|(8). -.PP -.Vb 3 -\& controlchan!\e -\& :!*,control,control.*,!control.cancel/!collabra\-internal\e -\& :Tc,Wnsm:/usr/local/news/bin/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 \fIinnd\fR\|(8) will send it all control messages except for -cancel messages. In this case, we also exclude any article with a -distribution of \f(CW\*(C`collabra\-internal\*(C'\fR. \fBcontrolchan\fR gets the storage -\&\s-1API\s0 token, the name of the sending site (for processing old-style ihave -and sendme control messages, be sure to read about \fIlogipaddr\fR in -\&\fIcontrolchan\fR\|(8)), and the message \s-1ID\s0 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 \s-1INN\s0. Also see the -install documentation that comes with \s-1INN\s0 for information about setting up -the standard newsfeeds entries used by most sites. -.SH "HISTORY" -.IX Header "HISTORY" -Written by Rich \f(CW$alz\fR for InterNetNews. Reformatted -and rewritten in \s-1POD\s0 by Russ Allbery . -.PP -$Id: newsfeeds.5 7880 2008-06-16 20:37:13Z iulius $ -.SH "SEE ALSO" -.IX Header "SEE ALSO" -\&\fIactive\fR\|(5), \fIbuffchan\fR\|(8), \fIcontrolchan\fR\|(8), \fIctlinnd\fR\|(8), \fIinn.conf\fR\|(5), \fIinnd\fR\|(8), -\&\fIinnfeed\fR\|(8), \fIinnxmit\fR\|(8), \fInntpsend\fR\|(8), \fIuwildmat\fR\|(3).