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