control.ctl - Specify handling of Usenet control messages
The file
pathetc/control.ctl 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.
If a
control.ctl.local file exists in
pathetc, it is read by
controlchan after
control.ctl (the resulting behaviour is as
though the contents of
control.ctl.local were at the end of
control.ctl). This local file is formatted like
control.ctl and
is intended to contain local customization. It is also automatically reloaded
when modified.
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>
Lines are matched in order and the last matching line in the file will be used,
except for checkgroups messages which are handled differently (every matching
line is used).
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. Besides,
the following special types are understood:
- /encoding/
- This type specifies the encoding of newgroup and
checkgroups control messages so that new descriptions could be decoded the
right way.
/encoding/:*:cn.*:gb18030
means that a description for a newsgroup in the Chinese cn.* hierarchy will
be decoded as though it were encoded in GB18030, unless a charset is
specified in the control message (in such a case, the charset mentioned in
the message is used). However, it is possible to override the mentioned
charset if "=force" is appended after the encoding. For
instance,
/encoding/:*:scout.forum.chinese:big5=force
means that the description for scout.forum.chinese will always be decoded as
though it were encoded in Big5, no matter the charset of the corresponding
control message.
The default value when no encoding is mentioned (or when the specified
encoding is unknown) is "CP1252".
The last matching line for a given newsgroup name in control.ctl will
be used.
- /localencoding/
- When this type is used, the line consist of only two
fields. The default value when this type does not appear in
control.ctl (or when the specified charset is unknown) is
equivalent to:
/localencoding/:utf-8
It means that new descriptions in the newsgroups file will be written
using UTF-8. And controlchan will try to read existing
descriptions, so as to see whether they should be updated, as though they
were encoded in UTF-8.
The last matching line in control.ctl will be used.
- /maxdocheckgroups/
- This type specifies the maximum number of changes that
could be made at one time by a checkgroups before bailing and mailing the
changes to the admin if no log file was specified. The default value is
10.
/maxdocheckgroups/:*:*:10
/maxdocheckgroups/:*:fr.*:20
Such a configuration means that a checkgroups containing 15 changes for the
French fr.* hierarchy (newgroups to add, remove or change the status) will
be automatically honoured whereas a checkgroups containing 15 changes for
france.* will only have the required changes mailed or logged.
The last matching line for a given newsgroup name in control.ctl will
be used.
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 (especially "?" matches exactly one
character, "*" matches zero or more characters and "|"
permits matching several patterns on the same line -- for instance
"comp.*|humanities.*" matches every newsgroup whose name begins with
"comp." or "humanities."). 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. It means that the change will be silently performed. For
checkgroups messages, depending on the value of /maxdocheckgroups/,
the shell commands that should be run may be mailed to the news
administrator (the argument to --with-news-master given at
configure time, "usenet" by default) instead of being performed.
If you always want notification of actions taken, use "doit=mail"
instead (see below).
-
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 "mail", 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 ".log". In other
words, an action of "doit=newgroup" will log to
pathlog/newgroup.log.
- drop
- No action is taken and the message is ignored. For
checkgroups messages, it means that the newsgroups mentioned will be
considered as not existent in the checkgroups for its subsequent process.
checkgroups:*:comp.*:doit
checkgroups:*:*binaries*:drop
will for instance remove every newsgroup whose name contains
"binaries" in the comp.* hierarchy, even though such groups are
mentioned in the checkgroups. (In that example, the removal is performed
by the doit action because drop does nothing by
itself.)
- 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(1) for
more details.
If no logging is specified (with = file as mentioned below), logging
will be done the same as with doit as described above.
-
verify-*=mail
- PGP verification is done as for the verify-* 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. The subject of the mail will contain information on whether
the script has already been run, depending on the value of
/maxdocheckgroups/.)
-
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. The initial line of the log will
contain information on whether the script has already been run, depending
on the value of /maxdocheckgroups/.)
- 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 without
taking any other action.
One of the difference between a
doit or
verify action and a
mail action for a checkgroups control message lies in what e-mail is
sent;
doit or
verify will mail the news administrator a shell
script (which may have already been run) to create, delete, or modify
newsgroups to match the checkgroups message, whereas
mail will just
mail relevant lines of the checkgroups for manual processing by the news
administrator.
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 honour. For more details on PGP-authenticated control
messages and the URL for downloading the PGP keys of major hierarchies, see
pgpverify(1).
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:[email protected]:comp.*:verify-news.announce.newgroups
newgroup:[email protected]:aus.*:mail
a newgroup coming from "
[email protected]" will be honoured 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.newgroups". If any newgroup claiming to be from
"
[email protected]" for a newsgroup in the aus.* hierarchy is
received, it too will be honoured. All other newgroup messages will be
ignored.
Besides, if a
control.ctl.local file exists and contains:
newgroup:*:comp.lang.*:drop
then a newgroup control article for comp.lang.awk will not be honoured even
though it comes from "
[email protected]" with a valid signature.
As for checkgroups, suppose your news server contains these groups for foo.*,
all of them being unmoderated ("y" status in the
active
file):
foo.bar1
foo.bar2.first
foo.bar2.second
foo.bar2.third
foo.bar3
foo.bar3.first
foo.bar3.second
foo.bar5
and you receive the following checkgroups by <
[email protected]> for foo.*:
foo.bar1 A valid newsgroup.
foo.bar3.first Only one newsgroup in foo.bar3.*.
foo.bar4 A newsgroup you want.
foo.bar5 A newsgroup you do not want.
foo.bar5.first Another newsgroup you do not want.
with the following
control.ctl entries:
/maxdocheckgroups/:*:foo.*:2
checkgroups:[email protected]:foo.*:verify-key-foo
checkgroups:[email protected]:foo.bar2.*:doit
checkgroups:[email protected]:foo.bar3.*:mail
checkgroups:[email protected]:foo.bar4|foo.bar4.*:doit
checkgroups:[email protected]:foo.bar5|foo.bar5.*:drop
Then, as
control.ctl is processed from bottom, here is what happens:
- 1.
- The newsgroups foo.bar5 and foo.bar5.first are marked as
unwanted. But nothing is done yet: other control.ctl entries have
to be processed with a real action and a set of newsgroups containing
foo.bar5 and foo.bar5.first.
- 2.
- The newsgroup foo.bar4 is silently created on the news
server, with the description "A newsgroup you want." added to
the newsgroups file. In the absence of encoding values (either in
the checkgroups message or in /encoding/ and
/localencoding), the default is to decode the sentence as CP1242
and re-encode it as UTF-8.
If "doit=mail" was used, a mail would be sent to the news
administrator to inform him that foo.bar4 was successfully created.
- 3.
- The newsgroup foo.bar3.second is no longer present. A mail
is sent to the news administrator with a shell script to execute. When it
is manually executed, foo.bar3.second will be removed.
Note that the descriptions are handled differently and have already been
updated without any manual intervention (foo.bar3.first now has the
description "Only one newsgroup in foo.bar3.*." and
foo.bar3.second no longer has a description).
- 4.
- The newsgroups foo.bar2.first, foo.bar2.second and
foo.bar2.third are no longer present. However, as the maximum number of
changes that could be made at one time by a checkgroups before bailing and
mailing the changes to the news administrator is 2, these newsgroups are
not removed. A mail is sent with a shell script to manually execute in
order to remove these groups from the news server.
Note that their descriptions are removed from the newsgroups file, as
well as any other possible descriptions for obsolete newsgroups in
foo.bar2.*.
- 5.
- The remaining entry is executed if the PGP verification of
the checkgroups message is successful. Otherwise, nothing is done
(especially, foo.bar5 remains on the news server).
In case the PGP signature is verified, foo.bar3 and foo.bar5 are removed
from the news server. This entry acts upon newsgroups marked as dropped in
its scope and newsgroups not already dealt with by previous
control.ctl entries (like foo.bar3 because only foo.bar3.* was
previously checked).
Note that if you had wanted to keep foo.bar3 or foo.bar5, you could have
added them to the localgroups file in pathetc.
Written by Rich $alz <
[email protected]> for InterNetNews. Rewritten in
POD by Russ Allbery <
[email protected]>.
controlchan(8),
inn.conf(5),
innd(8),
newsfeeds(5),
newsgroups(5),
pgpverify(1),
sh(1).