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 matching 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 doit=file
124 The action is performed as in doit, and additionally a log entry is
125 written to the specified log file file. If file is the word
126 "mail", the log entry is mailed to the news administrator instead.
127 An empty string is equivalent to /dev/null and says to log nothing.
128 If file starts with a slash, it is taken as the absolute filename
130 to use for the log file. Otherwise, the filename is formed by
131 prepending pathlog and a slash, and appending ".log". In other
132 words, an action of "doit=newgroup" will log to
133 pathlog/newgroup.log.
134 drop
136 No action is taken and the message is ignored. For checkgroups
137 messages, it means that the newsgroups mentioned will be considered
138 as not existent in the checkgroups for its subsequent process.
139 checkgroups:*:comp.*:doit
141 checkgroups:*:*binaries*:drop
142 will for instance remove every newsgroup whose name contains
144 "binaries" in the comp.* hierarchy, even though such groups are
145 mentioned in the checkgroups. (In that example, the removal is
146 performed by the doit action because drop does nothing by itself.)
147 verify-*
149 If the action starts with the string "verify-", as in:
150 verify-news.announce.newgroups
152 then PGP verification of the control message will be done and the
154 user ID of the key of the authenticated signer will be checked
155 against the expected identity defined by the rest of the string
156 ("news.announce.newgroups" in the above example). This
157 verification is done via pgpverify; see pgpverify(1) for more
158 details.
159 If no logging is specified (with =file as mentioned below), logging
161 will be done the same as with doit as described above.
162 verify-*=mail
164 PGP verification is done as for the verify-* action described
165 above, and notification of successful newgroup and rmgroup control
166 messages and the output of checkgroups messages will be mailed to
167 the news administrator. (In the case of checkgroups messages, this
168 means that the shell script that should be run will be mailed to
169 the administrator. The subject of the mail will contain
170 information on whether the script has already been run, depending
171 on the value of /maxdocheckgroups/.)
172 verify-*=file
174 PGP verification is done as for the verify-* action described
175 above, and a log entry is written to the specified file as
176 described in doit=file above. (In the case of checkgroups
177 messages, this means that the shell script output of the
178 checkgroups message will be written to that file. The initial line
179 of the log will contain information on whether the script has
180 already been run, depending on the value of /maxdocheckgroups/.)
181 log A one-line log message is sent to standard error. innd normally
183 directs this to pathlog/errlog.
184 log=file
186 A log entry is written to the specified log file, which is
187 interpreted as in doit=file described above.
188 mail
190 A mail message is sent to the news administrator without taking any
191 other action.
192 One of the difference between a doit or verify action and a mail action
194 for a checkgroups control message lies in what e-mail is sent; doit or
195 verify will mail the news administrator a shell script (which may have
196 already been run) to create, delete, or modify newsgroups to match the
197 checkgroups message, whereas mail will just mail relevant lines of the
198 checkgroups for manual processing by the news administrator.
199 Use of the verify action for processing newgroup, rmgroup and
201 checkgroups messages is STRONGLY recommended. Abuse of control
202 messages is rampant, and authentication via PGP signature is currently
203 the only reliable way to be sure that a control message comes from who
204 it claims to be from. Most major hierarchies are now issuing PGP-
205 authenticated control messages.
206 In order to use verify actions, the PGP key ring of the news user must
208 be populated with the PGP keys of the hierarchy maintainers whose
209 control messages you want to honour. For more details on PGP-
210 authenticated control messages and the URL for downloading the PGP keys
211 of major hierarchies, see pgpverify(1).
212 Control messages of type cancel are handled internally by innd and
214 cannot be affected by any of the mechanisms described here.
215
217 With the following three lines in control.ctl:
218 newgroup:*:*:drop
220 newgroup:group-admin@isc.org:comp.*:verify-news.announce.newgroups
221 newgroup:kre@munnari.oz.au:aus.*:mail
222 a newgroup coming from "group-admin@isc.org" will be honoured if it is
224 for a newsgroup in the comp.* hierarchy and if it has a valid signature
225 corresponding to the PGP key with a user ID of
226 "news.announce.newgroups". If any newgroup claiming to be from
227 "kre@munnari.oz.au" for a newsgroup in the aus.* hierarchy is received,
228 it too will be honoured. All other newgroup messages will be ignored.
229 Besides, if a control.ctl.local file exists and contains:
231 newgroup:*:comp.lang.*:drop
233 then a newgroup control article for comp.lang.awk will not be honoured
235 even though it comes from "group-admin@isc.org" with a valid signature.
236 As for checkgroups, suppose your news server contains these groups for
238 foo.*, all of them being unmoderated ("y" status in the active file):
239 foo.bar1
241 foo.bar2.first
242 foo.bar2.second
243 foo.bar2.third
244 foo.bar3
245 foo.bar3.first
246 foo.bar3.second
247 foo.bar5
248 and you receive the following checkgroups by <foo@bar.com> for foo.*:
250 foo.bar1 A valid newsgroup.
252 foo.bar3.first Only one newsgroup in foo.bar3.*.
253 foo.bar4 A newsgroup you want.
254 foo.bar5 A newsgroup you do not want.
255 foo.bar5.first Another newsgroup you do not want.
256 with the following control.ctl entries:
258 /maxdocheckgroups/:*:foo.*:2
260 checkgroups:foo@bar.com:foo.*:verify-key-foo
262 checkgroups:foo@bar.com:foo.bar2.*:doit
263 checkgroups:foo@bar.com:foo.bar3.*:mail
264 checkgroups:foo@bar.com:foo.bar4|foo.bar4.*:doit
265 checkgroups:foo@bar.com:foo.bar5|foo.bar5.*:drop
266 Then, as control.ctl is processed from bottom, here is what happens:
268 1. The newsgroups foo.bar5 and foo.bar5.first are marked as unwanted.
270 But nothing is done yet: other control.ctl entries have to be
271 processed with a real action and a set of newsgroups containing
272 foo.bar5 and foo.bar5.first.
273 2. The newsgroup foo.bar4 is silently created on the news server, with
275 the description "A newsgroup you want." added to the newsgroups
276 file. In the absence of encoding values (either in the checkgroups
277 message or in /encoding/ and /localencoding), the default is to
278 decode the sentence as CP1242 and re-encode it as UTF-8.
279 If "doit=mail" was used, a mail would be sent to the news
281 administrator to inform him that foo.bar4 was successfully created.
282 3. The newsgroup foo.bar3.second is no longer present. A mail is sent
284 to the news administrator with a shell script to execute. When it
285 is manually executed, foo.bar3.second will be removed.
286 Note that the descriptions are handled differently and have already
288 been updated without any manual intervention (foo.bar3.first now
289 has the description "Only one newsgroup in foo.bar3.*." and
290 foo.bar3.second no longer has a description).
291 4. The newsgroups foo.bar2.first, foo.bar2.second and foo.bar2.third
293 are no longer present. However, as the maximum number of changes
294 that could be made at one time by a checkgroups before bailing and
295 mailing the changes to the news administrator is 2, these
296 newsgroups are not removed. A mail is sent with a shell script to
297 manually execute in order to remove these groups from the news
298 server.
299 Note that their descriptions are removed from the newsgroups file,
301 as well as any other possible descriptions for obsolete newsgroups
302 in foo.bar2.*.
303 5. The remaining entry is executed if the PGP verification of the
305 checkgroups message is successful. Otherwise, nothing is done
306 (especially, foo.bar5 remains on the news server).
307 In case the PGP signature is verified, foo.bar3 and foo.bar5 are
309 removed from the news server. This entry acts upon newsgroups
310 marked as dropped in its scope and newsgroups not already dealt
311 with by previous control.ctl entries (like foo.bar3 because only
312 foo.bar3.* was previously checked).
313 Note that if you had wanted to keep foo.bar3 or foo.bar5, you could
315 have added them to the localgroups file in pathetc.
316
318 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Rewritten
319 in POD by Russ Allbery <eagle@eyrie.org>.
320
322 controlchan(8), inn.conf(5), innd(8), newsfeeds(5), newsgroups(5),
323 pgpverify(1), sh(1).
324INN 2.7.0 2022-07-10 CONTROL.CTL(5)