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:group-admin@isc.org:comp.*:verify-news.announce.newgroups
newgroup:kre@munnari.oz.au:aus.*:mail
a newgroup coming from
"group-admin@isc.org" 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 "kre@munnari.oz.au"
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
"group-admin@isc.org" 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 <foo@bar.com>
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:foo@bar.com:foo.*:verify-key-foo
checkgroups:foo@bar.com:foo.bar2.*:doit
checkgroups:foo@bar.com:foo.bar3.*:mail
checkgroups:foo@bar.com:foo.bar4|foo.bar4.*:doit
checkgroups:foo@bar.com: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 <rsalz@uunet.uu.net> for
InterNetNews. Rewritten in POD by Russ Allbery <eagle@eyrie.org>.
controlchan(8), inn.conf(5), innd(8), newsfeeds(5),
newsgroups(5), pgpverify(1), sh(1).