DESCRIPTION

       control.ctl in pathetc is used to determine what action is taken when a
       control message is received.  It is read by controlchan, which is nor-
       mally invoked as a channel program by innd.  When control.ctl is modi-
       fied, controlchan notices this automatically and reloads it.

       Blank lines and lines beginning with a number sign ("#") are ignored.
       All other lines should consist of four fields separated by colons:

           <type>:<from>:<newsgroups>:<action>

       The first field, <type>, is the type of control message for which this
       line is valid.  It should either be the name of a control message or
       the word "all" to indicate that it applies to all control messages.

       The second field, <from>, is a shell-style pattern that matches the
       e-mail address of the person posting the message (with the address
       first converted to lowercase).  The matching is done with rules equiva-
       lent to those of the shell's case statement; see sh(1) for more
       details.

       If the control message is a newgroup or rmgroup, the third field,
       <newsgroups>, is a shell-style pattern matching the newsgroup affected
       by the control message.  If the control message is a checkgroups, the
       third field is a shell-style pattern matching the newsgroups that
       should be processed for checking.  If the control message is of any
       other type, the third field is ignored.

       The fourth field, <action>, specifies what action to take with 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 the news
           administrator (the argument to --with-news-master given at config-
           ure time, "usenet" by default), but if notification of the action
           should always be sent, use "doit=mail" instead (see below).

       doifarg
           If the control message has an argument, this is equivalent to doit.
           If it does not have an argument, this is equivalent to mail.  This
           is only useful for entries for sendsys control messages, allowing a
           site to request its own newsfeeds entry by posting a "sendsys
           mysite" control message, but not allowing the entire newsfeeds file
           to be sent.  This was intended to partially counter so-called
           "sendsys bombs," where forged sendsys control messages were used to
           mailbomb people.

           Processing sendsys control messages is 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.
           No action is taken and the message is ignored.

       verify-*
           If the action starts with the string "verify-", as in:

               verify-news.announce.newgroups

           then PGP verification of the control message will be done and the
           user ID of the key of the authenticated signer will be checked
           against the expected identity defined by the rest of the string
           ("news.announce.newgroups" in the above example.  This verification
           is done via pgpverify; see pgpverify(8) for more details.

           If no logging is specified (with =file as mentioned below), notifi-
           cation of successful newgroup and rmgroup control messages and the
           output of checkgroups messages will be mailed to the news adminis-
           trator.

       verify-*=file
           PGP verification is done as for the verify-* action described
           above, and a log entry is written to the specified file as
           described in doit=file above.  (In the case of checkgroups mes-
           sages, this means that the shell script output of the checkgroups
           message will be written to that file.)

       log A one-line log message is sent to standard error.  innd normally
           directs this to pathlog/errlog.

       log=file
           A log entry is written to the specified log file, which is inter-
           preted as in doit=file described above.

       mail
           A mail message is sent to the news administrator.

       Processing of a checkgroups message will never actually change the
       active file (the list of groups carried by the server).  The difference
       between a doit or verify action and a mail action for a checkgroups
       control message lies only in what e-mail is sent; doit or verify 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 message, and if that
       mail is ignored, nothing will be changed.

       Lines are matched in order and the last matching line in the file will
       be used.

       Use of the verify action for processing newgroup, rmgroup, and check-
       groups messages is STRONGLY recommended.  Abuse of control messages is
       rampant, and authentication via PGP signature is currently the only
       reliable way to be sure that a control message comes from who it claims

           newgroup:*:*:drop
           newgroup:group-admin@isc.org:comp.*:verify-news.announce.newgroups
           newgroup:kre@munnari.oz.au:aus.*:mail

       a newgroup coming from "group-admin@isc.org" will be honored if it is
       for a newsgroup in the comp.* hierarchy and if it has a valid signature
       corresponding to the PGP key with a user ID of "news.announce.new-
       groups".  If any newgroup claiming to be from "kre@munnari.oz.au" for a
       newsgroup in the aus.* hierarchy is received, it too will be honored.
       All other newgroup messages will be ignored.

WARNINGS

       The third argument for a line affecting checkgroups does not affect
       whether the line matches.  It is only used after a matching line is
       found, to filter out which newsgroups listed in the checkgroups will be
       processed.  This means that a line like:

           checkgroups:*:*binaries*:drop

       will cause all checkgroups control messages to be dropped unless they
       match a line after this one in control.ctl, not just ignore newsgroups
       containing "binaries" in the name.  The general rule is to never use
       "*" in the second field for a line matching checkgroups messages.
       There is unfortunately no way to do what the author of a line like the
       above probably intended to do (yet).

HISTORY

       Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Rewritten
       in POD by Russ Allbery <rra@stanford.edu>.

       $Id: control.ctl.5 5912 2002-12-03 05:31:11Z vinocur $

SEE ALSO

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



INN 2.4.0                         2002-12-03                    CONTROL.CTL(5)