control.ctl - specify handling of Usenet control messages


DESCRIPTION

       The  file  <pathetc  in  inn.conf>/control.ctl  is used to
       determine what action is taken when a control  message  is
       received.  If <usecontrolchan in inn.conf> is ``true'', it
       is read by the controlchan script, which can be invoked as
       channel program by innd(8).  When control.ctl is modified,
       controlchan notices this automatically and reload it.   If
       <usecontrolchan  in  inn.conf> is ``false'', it is read by
       the parsecontrol script, which is called by all  the  con­
       trol  scripts.   (For  an  explanation  of how the control
       scripts are invoked, see innd(8).)

       The file consists of a series of lines;  blank  lines  and
       lines  beginning  with  a number sign (``#'') are ignored.
       All other lines consist of  four  fields  separated  by  a
       colon:
              message:from:newsgroups:action

       The  first field is the name of the message for which this
       line is valid.  It should be either the name of  the  con­
       trol  message or the word ``all'' to mean that it is valid
       for all messages.

       The second field is a shell-style pattern that matches the
       email  address  of  the  person posting the message.  (The
       poster's address is first converted  to  lowercase.)   The
       matching  is done using the shell's case statement (or the
       equivalent); see sh(1) for details.

       If the control message is ``newgroup'' or ``rmgroup'' then
       the  third  field  specifies  the shell-style pattern that
       must match the group being created  or  removed.   If  the
       control  message  is  ``checkgroups'' then the third field
       specifies the shell-style pattern that is used  to  deter­
       mine  which newsgroups are processed for checking.  If the
       control message is of a different type, then this field is
       ignored.

       The  fourth field specifies what action to take on control
       messages that match this line.  The following actions  are
       understood:

       doit   The  action requested by the control message should
              be performed.  In some cases,  the  control  script
              will         also        send        mail        to
              <USER specified with --with-news-master at config­
              ure>,  but  if  notification  of  the action should
              always be sent, doit=mail should  be  used  instead
              (see below).

              If  the  control  message  has an argument, this is
              treated as a ``doit'' action.  If no  argument  was
              given,  it is treated as a ``mail'' entry.  This is
              used in ``sendsys'' entries script so that  a  site
              can request its own newsfeeds(5) entry by posting a
              ``sendsys mysite'' article.   On  the  other  hand,
              sendsys  ``bombs''  ask  that  the entire newsfeeds
              file be sent to a forged reply-to address; by using
              ``doifarg''  such  messages  will  not be processed
              automatically.   (Processing  ``sendsys''   control
              messages  is  still not recommended, even with this
              work-around, unless they are authenticated in  some
              fashion.   The  risk  of having news servers turned
              into anonymous mail bombing services is too  high.)

       doit=file
              The action is performed, but a log entry is written
              to the specified log file, file.  If  file  is  the
              word  ``mail''  then  the record is mailed.  A null
              string is equivalent to /dev/null (in other  words,
              with a null string, nothing is logged).  A pathname
              that starts with a slash is taken as  the  absolute
              filename  to  use  as  the log.  Otherwise, the log
              entry is written to <pathlog in inn.conf>/file.log.
              The log is written by writelog (see newslog(8)).

       drop   No action is taken; the message is ignored.

       verify-*
              If  the  value  starts  with the string ``verify-''
              (for  example,  ``verify-news.announce.newgroups'')
              then  PGP  verification of the control message will
              be done  using  the  key  issued  by  the  ``user''
              defined    by   the   rest   of   the   string   --
              ``news.announce.newsgroups'' in this  example.   If
              no  logging  is  specified  (with  =file  mentioned
              below), notification of successful ``newgroup'' and
              ``rmgroup''  messages  and  the  output of ``check­
              groups'' messages will be mailed to the news admin­
              istrator.

       verify-*=file
              PGP  verification  is  done as for the ``verify-*''
              entries, and a log entry is written to  the  speci­
              fied  file.   (In  the case of ``checkgroups'' mes­
              sages, this means the shell script  output  of  the
              ``checkgroups''  message  will  be  written to that
              file.)

       log    A one-line log notice is sent  to  standard  error.
              innd(8)   normally   directs   this   to  the  file
              <pathlog in inn.conf>/errlog.

              A log entry is written to the specified  log  file,
              file, which is interpreted as described above.

       mail   A mail message is sent to the news administrator.

       Processing  of  a ``checkgroups'' message will never actu­
       ally change the active(5) file.  The difference between an
       action  of  doit  (or  verify)  and  an action of mail for
       ``checkgroups'' control messages lies only in what mail is
       sent; doit will mail the news administrator a shell script
       to create, delete,  or  modify  newsgroups  to  match  the
       ``checkgroups''  message,  whereas mail will just mail the
       entire message.  In either case,  the  news  administrator
       will  have to take action to implement the ``checkgroups''
       and if the mail is ignored, nothing will be changed.

       Lines are matched in order; the last match  found  in  the
       file  is the one that is used.  For example, with the fol­
       lowing three lines:

              newgroup:*:*:drop
              newgroup:group-admin@isc.org:comp.*|humanities.*|misc.*|news.*|\
              rec.*|sci.*|soc.*|talk.*:verify-news.announce.newgroups
              newgroup:kre@munnari.oz.au:aus.*:mail

       A newgroup coming from ``group-admin'' at  a  ISC  machine
       will be honored if it is one of the listed hierarchies and
       if it has a valid signature with the  ``news.announce.new­
       groups''  key.  If ``kre'' posts a newgroup message creat­
       ing ``aus.foo'', then mail will be sent.  All  other  new­
       group messages are ignored.

       Use  of  the  verify  action  for processing ``newgroup'',
       ``rmgroup'', and ``checkgroups'' messages is strongly rec­
       ommended.   Abuse  of  control  messages  is  rampant, and
       authentication via PGP signatures is  currently  the  only
       reliable  way to be sure that a control message comes from
       who it claims to be from.  Most major hierarchies are  now
       using PGP-authenticated control messages.

       In  order  to  use verify actions, the PGP key ring of the
       news user must be populated with the PGP keys of the hier­
       archy  maintainers  whose  control  messages  you  want to
       honor.  For more details on PGP-authenticated control mes­
       sages  and  the  URL for downloading the PGP keys of major
       hierarchies, see pgpverify(8).

       Control messages of type ``cancel'' are handled internally
       by  innd(8)  and cannot be controlled by any of the mecha­
       nisms described here.


HISTORY

       Written   by   Rich    $alz    <rsalz@uunet.uu.net>    for

       2000/08/17.


SEE ALSO

       controlchan(8),   inn.conf(5),   innd(8),    newsfeeds(5),
       pgpverify(8), scanlogs(8).


Man(1) output converted with man2html