1CONTROL.CTL(5)            InterNetNews Documentation            CONTROL.CTL(5)
2
3
4

NAME

6       control.ctl - Specify handling of Usenet control messages
7

DESCRIPTION

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
14       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
20       Blank lines and lines beginning with a number sign ("#") are ignored.
21       All other lines should consist of four fields separated by colons:
22
23           <type>:<from>:<newsgroups>:<action>
24
25       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
29       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
34       /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
39               /encoding/:*:cn.*:gb18030
40
41           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
48               /encoding/:*:scout.forum.chinese:big5=force
49
50           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
54           The default value when no encoding is mentioned (or when the
55           specified encoding is unknown) is "CP1252".
56
57           The last matching line for a given newsgroup name in control.ctl
58           will be used.
59
60       /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
65               /localencoding/:utf-8
66
67           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
72           The last matching line in control.ctl will be used.
73
74       /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
80               /maxdocheckgroups/:*:*:10
81               /maxdocheckgroups/:*:fr.*:20
82
83           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
89           The last matching line for a given newsgroup name in control.ctl
90           will be used.
91
92       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
98       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
109       The fourth field, <action>, specifies what action to take with control
110       messages that match this line.  The following actions are understood:
111
112       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
120           If you always want notification of actions taken, use "doit=mail"
121           instead (see below).
122
123       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
133           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
138       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
144           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
150       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
155               checkgroups:*:comp.*:doit
156               checkgroups:*:*binaries*:drop
157
158           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
163       verify-*
164           If the action starts with the string "verify-", as in:
165
166               verify-news.announce.newgroups
167
168           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
175           If no logging is specified (with =file as mentioned below), logging
176           will be done the same as with doit as described above.
177
178       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
188       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
197       log A one-line log message is sent to standard error.  innd normally
198           directs this to pathlog/errlog.
199
200       log=file
201           A log entry is written to the specified log file, which is
202           interpreted as in doit=file described above.
203
204       mail
205           A mail message is sent to the news administrator without taking any
206           other action.
207
208       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
215       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
222       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
228       Control messages of type cancel are handled internally by innd and
229       cannot be affected by any of the mechanisms described here.
230

EXAMPLES

232       With the following three lines in control.ctl:
233
234           newgroup:*:*:drop
235           newgroup:group-admin@isc.org:comp.*:verify-news.announce.newgroups
236           newgroup:kre@munnari.oz.au:aus.*:mail
237
238       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
245       Besides, if a control.ctl.local file exists and contains:
246
247           newgroup:*:comp.lang.*:drop
248
249       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
252       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
255           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
264       and you receive the following checkgroups by <foo@bar.com> for foo.*:
265
266           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
272       with the following control.ctl entries:
273
274           /maxdocheckgroups/:*:foo.*:2
275
276           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
282       Then, as control.ctl is processed from bottom, here is what happens:
283
284       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
289       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
295           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
298       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
302           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
307       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
315           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
319       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
323           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
329           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

HISTORY

333       Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Rewritten
334       in POD by Russ Allbery <rra@stanford.edu>.
335
336       $Id: control.ctl.pod 8804 2009-11-15 09:29:51Z iulius $
337

SEE ALSO

339       controlchan(8), inn.conf(5), innd(8), newsfeeds(5), newsgroups(5),
340       pgpverify(8), sh(1).
341
342
343
344INN 2.5.2                         2010-08-11                    CONTROL.CTL(5)
Impressum