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 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 ``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 ``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.
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:
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 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 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@uunet.uu.net> for InterNetNews.
This is revision 1.11.2.1, dated 2000/08/17.
