=head1 NAME control.ctl - Specify handling of Usenet control messages =head1 DESCRIPTION F in I is used to determine what action is taken when a control message is received. It is read by B, which is normally invoked as a channel program by B. When F is modified, B notices this automatically and reloads it. Blank lines and lines beginning with a number sign (C<#>) are ignored. All other lines should consist of four fields separated by colons: ::: The first field, , 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 C to indicate that it applies to all control messages. The second field, , 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 I statement; see sh(1) for more details. If the control message is a newgroup or rmgroup, the third field, , 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, , specifies what action to take with control messages that match this line. The following actions are understood: =over 4 =item B The action requested by the control message should be performed. For checkgroups messages, this means that the shell commands that should be run will be mailed to the news administrator (the argument to B<--with-news-master> given at configure time, C by default); for other commands, this means that the change will be silently performed. If you always want notification of actions taken, use C instead (see below). =item B If the control message has an argument, this is equivalent to B. If it does not have an argument, this is equivalent to B. This is only useful for entries for sendsys control messages, allowing a site to request its own F entry by posting a C control message, but not allowing the entire F 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. =item B=I The action is performed as in B, and additionally a log entry is written to the specified log file I. If I is the word C, the log entry is mailed to the news administrator instead. An empty string is equivalent to F and says to log nothing. If I starts with a slash, it is taken as the absolute filename to use for the log file. Otherwise, the filename is formed by prepending I and a slash and appending C<.log>. In other words, an action of C will log to I/newgroup.log. =item B No action is taken and the message is ignored. =item B If the action starts with the string C, 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 (C in the above example. This verification is done via B; see pgpverify(8) for more details. If no logging is specified (with =I as mentioned below), logging will be done the same as with B as described above. =item B=B PGP verification is done as for the B action described above, and notification of successful newgroup and rmgroup control messages and the output of checkgroups messages will be mailed to the news administrator. (In the case of checkgroups messages, this means that the shell script that should be run will be mailed to the administrator.) =item B=I PGP verification is done as for the B action described above, and a log entry is written to the specified file as described in B=I above. (In the case of checkgroups messages, this means that the shell script output of the checkgroups message will be written to that file.) =item B A one-line log message is sent to standard error. B normally directs this to I/errlog. =item B=I A log entry is written to the specified log file, which is interpreted as in B=I described above. =item B A mail message is sent to the news administrator without taking any other action. =back Processing of a checkgroups message will never actually change the F file (the list of groups carried by the server). The difference between a B or B action and a B action for a checkgroups control message lies only in what e-mail is sent; B or B will mail the news administrator a shell script to create, delete, or modify newsgroups to match the checkgroups message, whereas B 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 B 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 B 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 B and cannot be affected by any of the mechanisms described here. =head1 EXAMPLE With the following three lines in F: newgroup:*:*:drop newgroup:group-admin@isc.org:comp.*:verify-news.announce.newgroups newgroup:kre@munnari.oz.au:aus.*:mail a newgroup coming from C 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 C. If any newgroup claiming to be from C for a newsgroup in the aus.* hierarchy is received, it too will be honored. All other newgroup messages will be ignored. =head1 WARNINGS The third argument for a line affecting checkgroups does B 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 B checkgroups control messages to be dropped unless they match a line after this one in F, not just ignore newsgroups containing C in the name. The general rule is to never use C<*> 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). =head1 HISTORY Written by Rich $alz for InterNetNews. Rewritten in POD by Russ Allbery . $Id: control.ctl.pod 7569 2006-08-30 18:12:53Z eagle $ =head1 SEE ALSO controlchan(8), inn.conf(5), innd(8), newsfeeds(5), pgpverify(8), sh(1). =cut