control.ctl - Specify handling of Usenet control messages

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 normally invoked as a channel program by innd. When control.ctl is modified, controlchan notices this automatically and reloads it.

Blank lines and lines beginning with a number sign (CW#) 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 CWall 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 equivalent 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 configure time, CWusenet by default), but if notification of the action should always be sent, use CWdoit=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 CWsendsys 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.

doit=file

The action is performed as in doit, and additionally a log entry is written to the specified log file file. If file is the word CWmail, the log entry is mailed to the news administrator instead. An empty string is equivalent to /dev/null and says to log nothing. If file starts with a slash, it is taken as the absolute filename to use for the log file. Otherwise, the filename is formed by prepending pathlog and a slash and appending CW.log. In other words, an action of CWdoit=newgroup will log to pathlog/newgroup.log.

drop

No action is taken and the message is ignored.

verify-*

If the action starts with the string CWverify-, 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 (CWnews.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), notification of successful newgroup and rmgroup control messages and the output of checkgroups messages will be mailed to the news administrator.

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 messages, 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 interpreted 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 checkgroups 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 to be from. Most major hierarchies are now issuing 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 and cannot be affected by any of the mechanisms described here.

With the following three lines in control.ctl:

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

a newgroup coming from CWgroup-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 CWnews.announce.newgroups. If any newgroup claiming to be from CWkre@munnari.oz.au for a newsgroup in the aus.* hierarchy is received, it too will be honored. All other newgroup messages will be ignored.

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 CWbinaries in the name. The general rule is to never use CW* 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).

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

$Id: control.ctl.5,v 1.15 2002/12/03 05:31:09 vinocur Exp $

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