Provided by: inn_1.7.2q-44.1ubuntu2_amd64 bug

NAME

       newsfeeds - determine where Usenet articles get sent

DESCRIPTION

       The  file  /etc/news/newsfeeds  specifies  how  incoming articles should be distributed to
       other sites.  It is parsed by the InterNetNews server innd(8) when it starts up,  or  when
       directed to by ctlinnd(8).

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

       All  other  lines are interpreted as feed entries.  An entry should consist of four colon-
       separated fields; two of the fields may have optional sub-fields, marked off by  a  slash.
       Fields  or sub-fields that take multiple parameters should be separated by a comma.  Extra
       whitespace can cause problems.  Except for the  site  names,  case  is  significant.   The
       format of an entry is:
              sitename[/exclude,exclude,...]\
                   :pattern,pattern...[/distrib,distrib...]\
                   :flag,flag...\
                   :param
       Each field is described below.

       The  sitename is the name of the site to which a news article can be sent.  It is used for
       writing log entries and for determining if an article should be forwarded to a  site.   If
       sitename  already  appears in the article's Path header, then the article will not be sent
       to the site.  The name is usually whatever the remote site uses to identify itself in  the
       Path  line,  but  can  be almost any word that makes sense; special local entries (such as
       archivers or gateways) should probably end with an exclamation point  to  make  sure  that
       they  do  not have the same name as any real site.  For example, ``gateway'' is an obvious
       name for the local entry that forwards articles out to a mailing list.  If a site with the
       name  ``gateway''  posts  an article, when the local site receives the article it will see
       the name in the Path and not send the article to its own ``gateway'' entry.  See also  the
       description  of  the ``Ap'' flag, below.  If an entry has an exclusion sub-field, then the
       article will not be sent to that site if any of the names specified as excludes appear  in
       the  Path  header.   The same sitename can be used more than once — the appropriate action
       will be taken for each entry that should receive the article, regardless  of  the  name  —
       although  this  is  recommended  only  for  program feeds to avoid confusion.  Case is not
       significant in site names.

       The patterns specify which groups to send to the site  and  are  interpreted  to  build  a
       ``subscription  list''  for the site.  The default subscription is to get all groups.  The
       patterns in the field are wildmat(3)-style patterns, and are matched in order against  the
       list  of  newsgroups that the local site receives.  If the first character of a pattern is
       an  exclamation  mark,  then  any  groups  matching  the  pattern  are  removed  from  the
       subscription,  otherwise  any  matching  groups  are  added.   For example, to receive all
       ``comp'' groups, but only comp.sources.unix within the sources newsgroups,  the  following
       set of patterns can be used:
              comp.*,!comp.sources.*,comp.sources.unix
       There  are three things to note about this example.  The first is that the trailing ``.*''
       is required.  The second is that, again,  the  result  of  the  last  match  is  the  most
       important.  The third is that ``comp.sources.*'' could be written as ``comp.sources*'' but
       this would not have the same effect if there were a ``comp.sources-only'' group.

       There is also a way to subscribe to a newsgroup negatively.  That is to say, do  not  send
       this  group  even  if the article is cross-posted to a subscribed newsgroup.  If the first
       character of a pattern is an atsign ``@'', it means that any article  posted  to  a  group
       matching  the  pattern  will  not be sent even though the article may be cross-posted to a
       group which is subscribed.  The same rules of precedence apply in that the last  match  is
       the  one  which  counts.   For  example, if you want to prevent all articles posted to any
       "alt.binaries.warez" group from being propagated even if it  is  cross-posted  to  another
       "alt"  group or any other group for that matter, then the following set of patterns can be
       used:
              alt.*,@alt.binaries.warez.*,misc.*
       If you reverse the alt.* and alt.binaries.warez.* patterns, it would  nullify  the  atsign
       because  the result of the last match is the one that counts.  Using the above example, if
       an article is posted to one or more of the alt.binaries.warez.* groups and is cross-posted
       to misc.test, then the article is not sent.

       See innd(8) for details on the propagation of control messages.

       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 distribs are specified, then they are checked according to the
       following rules:

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

       2.     If a distrib starts with an exclamation point,  and  it  matches  the  Distribution
              header, then the article is not sent.

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

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

       If  an article has more than one distribution specified, then each one is 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 — the rules are used as a ``logical or.''  It is
       almost definitely a mistake to have a single feed that specifies distributions that  start
       with an exclamation point along with some that don't.

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

       The flags parameter specifies miscellaneous parameters.  They  may  be  specified  in  any
       order; flags that take values should have the value immediately after the flag letter with
       no whitespace.  The valid flags are:

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

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

       Achecks
              An article will only be sent to the site if it meets the requirements specified  in
              the checks, which should be chosen from the following set:
                   d    Distribution header required
                   p    Do not check Path header for the sitename before
                        propagating (the exclusions are still checked).

       Bhigh/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.  The first specifies the point at which the server can start
              draining the feed's I/O buffer, and the second 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.

       Fname  This flag specifies the name of the file that should be used if it is necessary  to
              begin  spooling  for the site (see below).  If name is not an absolute pathname, it
              is taken to be relative to /var/spool/news/out.going.  Then, if the destination  is
              a directory, the file togo in that directory will be used as filename.

       Gcount If this flag is specified, an article will only be sent to the site if it is posted
              to no more than count newsgroups.

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

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

       Nmodifiers
              The  newsgroups that a site receives are modified according to the modifiers, which
              should be chosen from the following set:
                   m    Only moderated groups
                   u    Only unmoderated groups

       Ssize  If the amount of data queued for the site gets to be larger than size  bytes,  then
              the  server  will  switch  to  spooling, appending to a file specified by the ``F''
              flag, or /var/spool/news/out.going/ sitename if the ``F'' flag  is  not  specified.
              Spooling usually happens only for channel or exploder feeds.

       Ttype  This  flag specifies the type of feed for the site.  Type should be a letter chosen
              from the following set:
                   c    Channel
                   f    File
                   l    Log entry only
                   m    Funnel (multiple entries feed into one)
                   p    Program
                   x    Exploder
              Each feed is described below in the section on feed types.  The default is Tf.

       Witems If a site is fed by file, channel, or exploder, this flag controls what information
              is  written.   If  a  site  is  fed by a program, only the asterisk (``*'') has any
              effect.  The items should be chosen from the following set:
                   b    Size of the article in bytes
                   f    Article's full pathname
                   g    The newsgroup the article is in;
                        if cross-posted, then the first of the groups this
                        site gets
                   m    Article's Message-ID
                   n    Article's pathname relative to the spool directory
                   p    The time the article was posted as seconds since epoch.
                   s    The site that fed the article to the server;
                        from the Path header
                   t    Time article was received as seconds since epoch
                   *    Names of the appropriate funnel entries;
                        or all sites that get the article
                   D    Value of the Distribution header;
                        ? if none present
                   H    All headers
                   N    Value of the Newsgroups header
                   O    Overview data
                   R    Information needed for replication
                   P    Path header information needed for inpaths
              More than one letter can be used; the entries will be separated  by  a  space,  and
              written in the order in which they are specified.  The default is Wn.

              The  ``H''  and  ``O''  items  are  intended  for  use by programs that create news
              overview databases.  If ``H'' is present, then the all the  article's  headers  are
              written  followed  by a blank line.  An Xref header (even if one does not appear in
              the filed article) and a Bytes header, specifying the article's size, will also  be
              part  of  the  headers.   If  used,  this  should  be the only item in the list; if
              preceeded by other items, however, a newline will be written  before  the  headers.
              The  ``O'' generates input to the overchan(8) program.  It, too, should be the only
              item in the list.

              The asterisk has special meaning.  It expands to  a  space-separated  list  of  all
              sites  that  received  the  current article.  If the site is the target of a funnel
              however (i.e., it is named by other sites which  have  a  ``Tm''  flag),  then  the
              asterisk  expands  to  the names of the funnel feeds that received the article.  If
              the site is fed by a program, then an asterisk in the param field will be  expanded
              into  the  list of funnel feeds that received the article.  A site fed by a program
              cannot get the site list unless it is the target of other ``Tm'' feeds.

       The interpretation of the param field depends on the type of feed,  and  is  explained  in
       more detail below in the section on feed types.  It can be omitted.

       The  site  named ME is special.  There should only be one such entry, and it should be the
       first entry in the file.  If the ME entry has a  subscription  list,  then  that  list  is
       automatically  prepended  to  the  subscription  list  of all other entries.  For example,
       ``*,!control,!junk,!foo.*'' can be used to set up the initial subscription  list  for  all
       feeds  so  that local postings are not propagated unless ``foo.* explicitly appears in the
       site's subscription list.  Note that most subscriptions should have ``!junk,!control''  in
       their  pattern list; see the discussion of ``control messages'' in innd(8).  (Unlike other
       news software, it does not affect what groups are received; that is done by the  active(5)
       file.)

       If  the  ME  entry  has  a  distribution  subfield,  then  only  articles  that  match the
       distribution list are accepted; all  other  articles  are  rejected.   A  commercial  news
       server,  for  example,  might  have  ``/!local''  to  reject  local  postings  from other,
       misconfigured, sites.

   FEED TYPES
       Innd provides four basic types of feeds: log, file, program, and channel.  An exploder  is
       a  special  type  of  channel.   In addition, several entries can feed into the same feed;
       these are funnel feeds, that refer to an entry that is one of the other types.  Note  that
       the  term ``feed'' is technically a misnomer, since the server does not transfer articles,
       but reports that an article should be sent to the site.

       The simplest feed is one that is fed by a log entry.  Other than a  mention  in  the  news
       logfile,  no  data  is  ever written out.  This is equivalent to a ``Tf'' entry writing to
       /dev/null except that no file is opened.

       A site fed by a file is simplest type of feed.  When the site should receive  an  article,
       one  line  is  written  to the file named by the param field.  If param is not an absolute
       pathname, it is taken to be relative to /var/spool/news/out.going.  If empty, the filename
       defaults to /var/spool/news/out.going/sitename.  This name should be unique.

       When  a  site  fed  by a file is flushed (see ctlinnd), the following steps are performed.
       The script doing the flush should have first renamed the file.  The server tries to  write
       out  any  buffered  data, and then closes the file.  The renamed file is now available for
       use.  The server will then re-open the original file, which will now get created.

       A site fed by a program has a process spawned for every article that  the  site  receives.
       The  param  field  must be a sprintf(3) format string that may have a single %s parameter,
       which will be given a pathname for the article, relative to the news spool directory.  The
       full  path  name  may be obtained by prefixing the %s in the param field by the news spool
       directory prefix.  Standard input will be set to the article or /dev/null if  the  article
       cannot be opened for some reason.  Standard output and error will be set to the error log.
       The process will run with the user and group ID of the /run/innd directory.  Innd will try
       to avoid spawning a shell if the command has no shell meta-characters; this feature can be
       defeated by appending a semi-colon to the end of the command.  The full  pathname  of  the
       program to be run must be specified; for security, PATH is not searched.

       If  the  entry  is  the  target of a funnel, and if the ``W*'' flag is used, then a single
       asterisk may be used in the param field where it will be replaced  by  the  names  of  the
       sites  that  fed  into the funnel.  If the entry is not a funnel, or if the ``W*'' flag is
       not used, then the asterisk has no special meaning.

       Flushing a site fed by a program does no action.

       When a site is fed by a channel or exploder, the param field names the process  to  start.
       Again,  the  full  pathname  of the process must be given.  When the site is to receive an
       article, the process receives a line on its standard input telling it about  the  article.
       Standard output and error, and the user and group ID of the all sub-process are set as for
       a program feed, above.  If the process exits, it will be restarted.  If the process cannot
       be     started,     the     server     will     spool    input    to    a    file    named
       /var/spool/news/out.going/sitename.  It will then try  to  start  the  process  some  time
       later.

       When a site fed by a channel or exploder is flushed, the server closes down its end of the
       pipe.  Any pending data that has not been written will be spooled; see the description  of
       the  ``S''  flag,  above.  No signal is sent; it is up to the program to notice EOF on its
       standard input and exit.  The server then starts a new process.

       Exploders are a superset of channel feeds.  In addition to channel behavior, exploders can
       be  sent  command  lines.   These  lines  start  with  an  exclamation  point,  and  their
       interpretation is up to the exploder.  The following messages are generated  automatically
       by the server:
              newgroup group
              rmgroup group
              flush
              flush site
       These  messages  are  sent  when  the  ctlinnd command of the same name is received by the
       server.  In addition, the ``send'' command can be used to send an arbitrary  command  line
       to the exploder child-process.  The primary exploder is buffchan(8).

       Funnel  feeds  provide  a way of merging several site entries into a single output stream.
       For a site feeding into a funnel, the param field names the actual  entry  that  does  the
       feeding.

       For  more  details  on  setting up different types of news feeds, see the INN installation
       manual.

EXAMPLES

              ##  Initial subscription list and our distributions.
              ME:*,!junk,!foo.*/world,usa,na,ne,foo,ddn,gnu,inet\
                   ::
              ##  Feed all moderated source postings to an archiver
              source-archive!:!*,*sources*,!*wanted*,!*.d\
                   :Tc,Wn:/usr/lib/news/bin/archive -f -i \
                       /usr/spool/news.archive/INDEX
              ##  Watch for big postings
              watcher!:*\
                   :Tc,Wbnm\
                   :exec awk '$1 > 1000000 { print "BIG", $2, $3 }' >/dev/console
              ##  A UUCP feed, where we try to keep the "batching" between 4 and 1K.
              ihnp4:/world,usa,na,ddn,gnu\
                   :Tf,Wnb,B4096/1024:
              ##  Usenet as mail; note ! in funnel name to avoid Path conflicts.
              ##  Can't use ! in "fred" since it would like look a UUCP address.
              fred:!*,comp.sources.unix,comp.sources.bugs\
                   :Tm:mailer!
              barney@bar.com:!*,news.software.nntp,comp.sources.bugs\
                   :Tm:mailer!
              mailer!:!*\
                   :W*,Tp:/usr/ucb/Mail -s "News article" *
              ##  NNTP feeds fed off-line via nntpsend or equivalent.
              feed1::Tf,Wnm:feed1.domain.name
              peer.foo.com:foo.*:Tf,Wnm:peer.foo.com
              ##  Real-time transmission.
              mit.edu:/world,usa,na,ne,ddn,gnu,inet\
                   :Tc,Wnm:/usr/lib/news/bin/nntplink -i stdin mit.edu
              ##  Two sites feeding into a hypothetical NNTP fan-out program:
              nic.near.net:\
                   :Tm:nntpfunnel1
              uunet.uu.net/uunet:!ne.*/world,usa,na,foo,ddn,gnu,inet\
                   :Tm:nntpfunnel1
              nntpfunnel1:!*\
                   :Tc,Wmn*:/usr/lib/news/bin/nntpfanout
              ##  A UUCP site that wants comp.* and moderated soc groups
              uucpsite!comp:!*,comp.*/world,usa,na,gnu\
                   :Tm:uucpsite
              uucpsite!soc:!*,soc.*/world,usa,na,gnu\
                   :Tm,Nm:uucpsite
              uucpsite:!*\
                   :Tf,Wnb:/usr/spool/batch/uucpsite

       The last two sets of entries show  how  funnel  feeds  can  be  used.   For  example,  the
       nntpfanout program would receive lines like the following on its standard input:
              <123@litchi.foo.com> comp/sources/unix/888 nic.near.net uunet.uu.net
              <124@litchi.foo.com> ne/general/1003 nic.near.net
       Since  the  UUCP  funnel  is  only  destined  for one site, the asterisk is not needed and
       entries like the following will be written into the file:
              <qwe#37x@snark.uu.net> comp/society/folklore/3
              <123@litchi.foo.com> comp/sources/unix/888

HISTORY

       Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  This is revision 1.35,  dated
       1996/12/17.

SEE ALSO

       active(5), buffchan(8), ctlinnd(8), innd(8), wildmat(3).

                                                                                     NEWSFEEDS(5)