1CONTROL.CTL(5) InterNetNews Documentation CONTROL.CTL(5)
2
6 control.ctl - Specify handling of Usenet control messages
7
9 The file pathetc/control.ctl is used to determine what action is taken
10 when a control message is received. It is read by controlchan, which
11 is normally invoked as a channel program by innd. When control.ctl is
12 modified, controlchan notices this automatically and reloads it.
13 If a control.ctl.local file exists in pathetc, it is read by
15 controlchan after control.ctl (the resulting behaviour is as though the
16 contents of control.ctl.local were at the end of control.ctl). This
17 local file is formatted like control.ctl and is intended to contain
18 local customization. It is also automatically reloaded when modified.
19 Blank lines and lines beginning with a number sign ("#") are ignored.
21 All other lines should consist of four fields separated by colons:
22 <type>:<from>:<newsgroups>:<action>
24 Lines are matched in order and the last matching line in the file will
26 be used, except for checkgroups messages which are handled differently
27 (every matching line is used).
28 The first field, <type>, is the type of control message for which this
30 line is valid. It should either be the name of a control message or
31 the word "all" to indicate that it applies to all control messages.
32 Besides, the following special types are understood:
33 /encoding/
35 This type specifies the encoding of newgroup and checkgroups
36 control messages so that new descriptions could be decoded the
37 right way.
38 /encoding/:*:cn.*:gb18030
40 means that a description for a newsgroup in the Chinese cn.*
42 hierarchy will be decoded as though it were encoded in GB18030,
43 unless a charset is specified in the control message (in such a
44 case, the charset mentioned in the message is used). However, it
45 is possible to override the mentioned charset if "=force" is
46 appended after the encoding. For instance,
47 /encoding/:*:scout.forum.chinese:big5=force
49 means that the description for scout.forum.chinese will always be
51 decoded as though it were encoded in Big5, no matter the charset of
52 the corresponding control message.
53 The default value when no encoding is mentioned (or when the
55 specified encoding is unknown) is "CP1252".
56 The last matching line for a given newsgroup name in control.ctl
58 will be used.
59 /localencoding/
61 When this type is used, the line consist of only two fields. The
62 default value when this type does not appear in control.ctl (or
63 when the specified charset is unknown) is equivalent to:
64 /localencoding/:utf-8
66 It means that new descriptions in the newsgroups file will be
68 written using UTF-8. And controlchan will try to read existing
69 descriptions, so as to see whether they should be updated, as
70 though they were encoded in UTF-8.
71 The last matching line in control.ctl will be used.
73 /maxdocheckgroups/
75 This type specifies the maximum number of changes that could be
76 made at one time by a checkgroups before bailing and mailing the
77 changes to the admin if no log file was specified. The default
78 value is 10.
79 /maxdocheckgroups/:*:*:10
81 /maxdocheckgroups/:*:fr.*:20
82 Such a configuration means that a checkgroups containing 15 changes
84 for the French fr.* hierarchy (newgroups to add, remove or change
85 the status) will be automatically honoured whereas a checkgroups
86 containing 15 changes for france.* will only have the required
87 changes mailed or logged.
88 The last matching line for a given newsgroup name in control.ctl
90 will be used.
91 The second field, <from>, is a shell-style pattern that matches the
93 e-mail address of the person posting the message (with the address
94 first converted to lowercase). The matching is done with rules
95 equivalent to those of the shell's case statement; see sh(1) for more
96 details.
97 If the control message is a newgroup or rmgroup, the third field,
99 <newsgroups>, is a shell-style pattern matching the newsgroup affected
100 by the control message (especially "?" matches exactly one character,
101 "*" matches zero or more characters and "|" permits to match several
102 patterns on the same line -- for instance "comp.*|humanities.*"
103 matches every newsgroup whose name begins with "comp." or
104 "humanities."). If the control message is a checkgroups, the third
105 field is a shell-style pattern matching the newsgroups that should be
106 processed for checking. If the control message is of any other type,
107 the third field is ignored.
108 The fourth field, <action>, specifies what action to take with control
110 messages that match this line. The following actions are understood:
111 doit
113 The action requested by the control message should be performed.
114 It means that the change will be silently performed. For
115 checkgroups messages, depending on the value of /maxdocheckgroups/,
116 the shell commands that should be run may be mailed to the news
117 administrator (the argument to --with-news-master given at
118 configure time, "usenet" by default) instead of being performed.
119 If you always want notification of actions taken, use "doit=mail"
121 instead (see below).
122 doifarg
124 If the control message has an argument, this is equivalent to doit.
125 If it does not have an argument, this is equivalent to mail. This
126 is only useful for entries for sendsys control messages, allowing a
127 site to request its own newsfeeds entry by posting a "sendsys
128 mysite" control message, but not allowing the entire newsfeeds file
129 to be sent. This was intended to partially counter so-called
130 "sendsys bombs", where forged sendsys control messages were used to
131 mailbomb people.
132 Processing sendsys control messages is not recommended even with
134 this work-around unless they are authenticated in some fashion.
135 The risk of having news servers turned into anonymous mail bombing
136 services is too high.
137 doit=file
139 The action is performed as in doit, and additionally a log entry is
140 written to the specified log file file. If file is the word
141 "mail", the log entry is mailed to the news administrator instead.
142 An empty string is equivalent to /dev/null and says to log nothing.
143 If file starts with a slash, it is taken as the absolute filename
145 to use for the log file. Otherwise, the filename is formed by
146 prepending pathlog and a slash, and appending ".log". In other
147 words, an action of "doit=newgroup" will log to
148 pathlog/newgroup.log.
149 drop
151 No action is taken and the message is ignored. For checkgroups
152 messages, it means that the newsgroups mentioned will be considered
153 as not existent in the checkgroups for its subsequent process.
154 checkgroups:*:comp.*:doit
156 checkgroups:*:*binaries*:drop
157 will for instance remove every newsgroup whose name contains
159 "binaries" in the comp.* hierarchy, even though such groups are
160 mentioned in the checkgroups. (In that example, the removal is
161 performed by the doit action because drop does nothing by itself.)
162 verify-*
164 If the action starts with the string "verify-", as in:
165 verify-news.announce.newgroups
167 then PGP verification of the control message will be done and the
169 user ID of the key of the authenticated signer will be checked
170 against the expected identity defined by the rest of the string
171 ("news.announce.newgroups" in the above example). This
172 verification is done via pgpverify; see pgpverify(8) for more
173 details.
174 If no logging is specified (with =file as mentioned below), logging
176 will be done the same as with doit as described above.
177 verify-*=mail
179 PGP verification is done as for the verify-* action described
180 above, and notification of successful newgroup and rmgroup control
181 messages and the output of checkgroups messages will be mailed to
182 the news administrator. (In the case of checkgroups messages, this
183 means that the shell script that should be run will be mailed to
184 the administrator. The subject of the mail will contain
185 information on whether the script has already been run, depending
186 on the value of /maxdocheckgroups/.)
187 verify-*=file
189 PGP verification is done as for the verify-* action described
190 above, and a log entry is written to the specified file as
191 described in doit=file above. (In the case of checkgroups
192 messages, this means that the shell script output of the
193 checkgroups message will be written to that file. The initial line
194 of the log will contain information on whether the script has
195 already been run, depending on the value of /maxdocheckgroups/.)
196 log A one-line log message is sent to standard error. innd normally
198 directs this to pathlog/errlog.
199 log=file
201 A log entry is written to the specified log file, which is
202 interpreted as in doit=file described above.
203 mail
205 A mail message is sent to the news administrator without taking any
206 other action.
207 One of the difference between a doit or verify action and a mail action
209 for a checkgroups control message lies in what e-mail is sent; doit or
210 verify will mail the news administrator a shell script (which may have
211 already been run) to create, delete, or modify newsgroups to match the
212 checkgroups message, whereas mail will just mail relevant lines of the
213 checkgroups for manual processing by the news administrator.
214 Use of the verify action for processing newgroup, rmgroup and
216 checkgroups messages is STRONGLY recommended. Abuse of control
217 messages is rampant, and authentication via PGP signature is currently
218 the only reliable way to be sure that a control message comes from who
219 it claims to be from. Most major hierarchies are now issuing PGP-
220 authenticated control messages.
221 In order to use verify actions, the PGP key ring of the news user must
223 be populated with the PGP keys of the hierarchy maintainers whose
224 control messages you want to honour. For more details on PGP-
225 authenticated control messages and the URL for downloading the PGP keys
226 of major hierarchies, see pgpverify(8).
227 Control messages of type cancel are handled internally by innd and
229 cannot be affected by any of the mechanisms described here.
230
232 With the following three lines in control.ctl:
233 newgroup:*:*:drop
235 newgroup:group-admin@isc.org:comp.*:verify-news.announce.newgroups
236 newgroup:kre@munnari.oz.au:aus.*:mail
237 a newgroup coming from "group-admin@isc.org" will be honoured if it is
239 for a newsgroup in the comp.* hierarchy and if it has a valid signature
240 corresponding to the PGP key with a user ID of
241 "news.announce.newgroups". If any newgroup claiming to be from
242 "kre@munnari.oz.au" for a newsgroup in the aus.* hierarchy is received,
243 it too will be honoured. All other newgroup messages will be ignored.
244 Besides, if a control.ctl.local file exists and contains:
246 newgroup:*:comp.lang.*:drop
248 then a newgroup control article for comp.lang.awk will not be honoured
250 even though it comes from "group-admin@isc.org" with a valid signature.
251 As for checkgroups, suppose your news server contains these groups for
253 foo.*, all of them being unmoderated ("y" status in the active file):
254 foo.bar1
256 foo.bar2.first
257 foo.bar2.second
258 foo.bar2.third
259 foo.bar3
260 foo.bar3.first
261 foo.bar3.second
262 foo.bar5
263 and you receive the following checkgroups by <foo@bar.com> for foo.*:
265 foo.bar1 A valid newsgroup.
267 foo.bar3.first Only one newsgroup in foo.bar3.*.
268 foo.bar4 A newsgroup you want.
269 foo.bar5 A newsgroup you do not want.
270 foo.bar5.first Another newsgroup you do not want.
271 with the following control.ctl entries:
273 /maxdocheckgroups/:*:foo.*:2
275 checkgroups:foo@bar.com:foo.*:verify-key-foo
277 checkgroups:foo@bar.com:foo.bar2.*:doit
278 checkgroups:foo@bar.com:foo.bar3.*:mail
279 checkgroups:foo@bar.com:foo.bar4|foo.bar4.*:doit
280 checkgroups:foo@bar.com:foo.bar5|foo.bar5.*:drop
281 Then, as control.ctl is processed from bottom, here is what happens:
283 1. The newsgroups foo.bar5 and foo.bar5.first are marked as unwanted.
285 But nothing is done yet: other control.ctl entries have to be
286 processed with a real action and a set of newsgroups containing
287 foo.bar5 and foo.bar5.first.
288 2. The newsgroup foo.bar4 is silently created on the news server, with
290 the description "A newsgroup you want." added to the newsgroups
291 file. In the absence of encoding values (either in the checkgroups
292 message or in /encoding/ and /localencoding), the default is to
293 decode the sentence as CP1242 and reencode it as UTF-8.
294 If "doit=mail" was used, a mail would be sent to the news
296 administrator to inform him that foo.bar4 was successfully created.
297 3. The newsgroup foo.bar3.second is no longer present. A mail is sent
299 to the news administrator with a shell script to execute. When it
300 is manually executed, foo.bar3.second will be removed.
301 Note that the descriptions are handled differently and have already
303 been updated without any manual intervention (foo.bar3.first now
304 has the description "Only one newsgroup in foo.bar3.*." and
305 foo.bar3.second no longer has a description).
306 4. The newsgroups foo.bar2.first, foo.bar2.second and foo.bar2.third
308 are no longer present. However, as the maximum number of changes
309 that could be made at one time by a checkgroups before bailing and
310 mailing the changes to the news administrator is 2, these
311 newsgroups are not removed. A mail is sent with a shell script to
312 manually execute in order to remove these groups from the news
313 server.
314 Note that their descriptions are removed from the newsgroups file,
316 as well as any other possible descriptions for obsolete newsgroups
317 in foo.bar2.*.
318 5. The remaining entry is executed if the PGP verification of the
320 checkgroups message is successful. Otherwise, nothing is done
321 (especially, foo.bar5 remains on the news server).
322 In case the PGP signature is verified, foo.bar3 and foo.bar5 are
324 removed from the news server. This entry acts upon newsgroups
325 marked as dropped in its scope and newsgroups not already dealt
326 with by previous control.ctl entries (like foo.bar3 because only
327 foo.bar3.* was previously checked).
328 Note that if you had wanted to keep foo.bar3 or foo.bar5, you could
330 have added them to the localgroups file in pathetc.
331
333 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Rewritten
334 in POD by Russ Allbery <rra@stanford.edu>.
335 $Id: control.ctl.pod 8804 2009-11-15 09:29:51Z iulius $
337
339 controlchan(8), inn.conf(5), innd(8), newsfeeds(5), newsgroups(5),
340 pgpverify(8), sh(1).
341INN 2.5.2 2010-08-11 CONTROL.CTL(5)