CONTROL.CTL(5)                                                                                         CONTROL.CTL(5)



NAME
       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 control 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
       control 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 determine 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 configure>, but if notification of
              the action should always be sent, doit=mail should be used instead (see below).

       doifarg
              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  mes-
              sages is still not recommended, even with this work-around, unless they are authenticated in some fash-
              ion.  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 ''checkgroups'' messages will be mailed to the news administrator.

       verify-*=file
              PGP verification is done as for the ''verify-*'' entries, and a log entry is written to  the  specified
              file.   (In  the  case  of ''checkgroups'' messages, this means the shell script output of the ''check-
              groups'' 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.

       log=file
              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 actually 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
       following three lines:

              newgroup:*:*:drop
              newgroup:group-admin AT isc.org:comp.*|humanities.*|misc.*|news.*|\
              rec.*|sci.*|soc.*|talk.*:verify-news.announce.newgroups
              newgroup:kre AT munnari.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.newgroups'' key.  If ''kre'' posts a newgroup message
       creating ''aus.foo'', then mail will be sent.  All other newgroup messages are ignored.

       Use  of  the  verify action for processing ''newgroup'', ''rmgroup'', and ''checkgroups'' messages is strongly
       recommended.  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 hierar-
       chies 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
       hierarchy maintainers whose control messages you want to honor.  For more details on PGP-authenticated control
       messages 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
       mechanisms described here.

HISTORY
       Written by Rich $alz <rsalz AT uunet.net> for InterNetNews.  This is revision 1.11.2.1, dated 2000/08/17.

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



                                                                                                       CONTROL.CTL(5)