chiark / gitweb /
debugging for thing that crashed
[innduct.git] / doc / pod / control.ctl.pod
1 =head1 NAME
2
3 control.ctl - Specify handling of Usenet control messages
4
5 =head1 DESCRIPTION
6
7 F<control.ctl> in I<pathetc> is used to determine what action is taken
8 when a control message is received.  It is read by B<controlchan>, which
9 is normally invoked as a channel program by B<innd>.  When F<control.ctl>
10 is modified, B<controlchan> notices this automatically and reloads it.
11
12 Blank lines and lines beginning with a number sign (C<#>) are ignored.
13 All other lines should consist of four fields separated by colons:
14
15     <type>:<from>:<newsgroups>:<action>
16
17 The first field, <type>, is the type of control message for which this
18 line is valid.  It should either be the name of a control message or the
19 word C<all> to indicate that it applies to all control messages.
20
21 The second field, <from>, is a shell-style pattern that matches the e-mail
22 address of the person posting the message (with the address first
23 converted to lowercase).  The matching is done with rules equivalent to
24 those of the shell's I<case> statement; see sh(1) for more details.
25
26 If the control message is a newgroup or rmgroup, the third field,
27 <newsgroups>, is a shell-style pattern matching the newsgroup affected by
28 the control message.  If the control message is a checkgroups, the third
29 field is a shell-style pattern matching the newsgroups that should be
30 processed for checking.  If the control message is of any other type, the
31 third field is ignored.
32
33 The fourth field, <action>, specifies what action to take with control
34 messages that match this line.  The following actions are understood:
35
36 =over 4
37
38 =item B<doit>
39
40 The action requested by the control message should be performed.  For
41 checkgroups messages, this means that the shell commands that should
42 be run will be mailed to the news administrator (the argument to
43 B<--with-news-master> given at configure time, C<usenet> by default); for
44 other commands, this means that the change will be silently performed.  If
45 you always want notification of actions taken, use C<doit=mail> instead (see
46 below).
47
48 =item B<doifarg>
49
50 If the control message has an argument, this is equivalent to B<doit>.  If
51 it does not have an argument, this is equivalent to B<mail>.  This is only
52 useful for entries for sendsys control messages, allowing a site to
53 request its own F<newsfeeds> entry by posting a C<sendsys mysite> control
54 message, but not allowing the entire F<newsfeeds> file to be sent.  This
55 was intended to partially counter so-called "sendsys bombs," where forged
56 sendsys control messages were used to mailbomb people.
57
58 Processing sendsys control messages is not recommended even with this
59 work-around unless they are authenticated in some fashion.  The risk of
60 having news servers turned into anonymous mail bombing services is too
61 high.
62
63 =item B<doit>=I<file>
64
65 The action is performed as in B<doit>, and additionally a log entry is
66 written to the specified log file I<file>.  If I<file> is the word
67 C<mail>, the log entry is mailed to the news administrator instead.  An
68 empty string is equivalent to F</dev/null> and says to log nothing.
69
70 If I<file> starts with a slash, it is taken as the absolute filename to
71 use for the log file.  Otherwise, the filename is formed by prepending
72 I<pathlog> and a slash and appending C<.log>.  In other words, an action
73 of C<doit=newgroup> will log to I<pathlog>/newgroup.log.
74
75 =item B<drop>
76
77 No action is taken and the message is ignored.
78
79 =item B<verify-*>
80
81 If the action starts with the string C<verify->, as in:
82
83     verify-news.announce.newgroups
84
85 then PGP verification of the control message will be done and the user ID
86 of the key of the authenticated signer will be checked against the
87 expected identity defined by the rest of the string
88 (C<news.announce.newgroups> in the above example.  This verification is
89 done via B<pgpverify>; see pgpverify(8) for more details.
90
91 If no logging is specified (with =I<file> as mentioned below), logging will
92 be done the same as with B<doit> as described above.
93
94 =item B<verify-*>=B<mail>
95
96 PGP verification is done as for the B<verify-*> action described above, and
97 notification of successful newgroup and rmgroup control messages and the
98 output of checkgroups messages will be mailed to the news administrator.
99 (In the case of checkgroups messages, this means that the shell script that
100 should be run will be mailed to the administrator.)
101
102 =item B<verify-*>=I<file>
103
104 PGP verification is done as for the B<verify-*> action described above,
105 and a log entry is written to the specified file as described in
106 B<doit>=I<file> above.  (In the case of checkgroups messages, this means
107 that the shell script output of the checkgroups message will be written to
108 that file.)
109
110 =item B<log>
111
112 A one-line log message is sent to standard error.  B<innd> normally
113 directs this to I<pathlog>/errlog.
114
115 =item B<log>=I<file>
116
117 A log entry is written to the specified log file, which is interpreted as
118 in B<doit>=I<file> described above.
119
120 =item B<mail>
121
122 A mail message is sent to the news administrator without taking any other
123 action.
124
125 =back
126
127 Processing of a checkgroups message will never actually change the
128 F<active> file (the list of groups carried by the server).  The difference
129 between a B<doit> or B<verify> action and a B<mail> action for a
130 checkgroups control message lies only in what e-mail is sent; B<doit> or
131 B<verify> will mail the news administrator a shell script to create,
132 delete, or modify newsgroups to match the checkgroups message, whereas
133 B<mail> will just mail the entire message.  In either case, the news
134 administrator will have to take action to implement the checkgroups
135 message, and if that mail is ignored, nothing will be changed.
136
137 Lines are matched in order and the last matching line in the file will be
138 used.
139
140 Use of the B<verify> action for processing newgroup, rmgroup, and
141 checkgroups messages is STRONGLY recommended.  Abuse of control messages
142 is rampant, and authentication via PGP signature is currently the only
143 reliable way to be sure that a control message comes from who it claims to
144 be from.  Most major hierarchies are now issuing PGP-authenticated control
145 messages.
146
147 In order to use B<verify> actions, the PGP key ring of the news user must
148 be populated with the PGP keys of the hierarchy maintainers whose control
149 messages you want to honor.  For more details on PGP-authenticated control
150 messages and the URL for downloading the PGP keys of major hierarchies,
151 see pgpverify(8).
152
153 Control messages of type cancel are handled internally by B<innd> and
154 cannot be affected by any of the mechanisms described here.
155
156 =head1 EXAMPLE
157
158 With the following three lines in F<control.ctl>:
159
160     newgroup:*:*:drop
161     newgroup:group-admin@isc.org:comp.*:verify-news.announce.newgroups
162     newgroup:kre@munnari.oz.au:aus.*:mail
163
164 a newgroup coming from C<group-admin@isc.org> will be honored if it is for
165 a newsgroup in the comp.* hierarchy and if it has a valid signature
166 corresponding to the PGP key with a user ID of C<news.announce.newgroups>.
167 If any newgroup claiming to be from C<kre@munnari.oz.au> for a newsgroup
168 in the aus.* hierarchy is received, it too will be honored.  All other
169 newgroup messages will be ignored.
170
171 =head1 WARNINGS
172
173 The third argument for a line affecting checkgroups does B<not> affect
174 whether the line matches.  It is only used after a matching line is found,
175 to filter out which newsgroups listed in the checkgroups will be
176 processed.  This means that a line like:
177
178     checkgroups:*:*binaries*:drop
179
180 will cause B<all> checkgroups control messages to be dropped unless they
181 match a line after this one in F<control.ctl>, not just ignore newsgroups
182 containing C<binaries> in the name.  The general rule is to never use C<*>
183 in the second field for a line matching checkgroups messages.  There is
184 unfortunately no way to do what the author of a line like the above
185 probably intended to do (yet).
186
187 =head1 HISTORY
188
189 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Rewritten in
190 POD by Russ Allbery <rra@stanford.edu>.
191
192 $Id: control.ctl.pod 7569 2006-08-30 18:12:53Z eagle $
193
194 =head1 SEE ALSO
195
196 controlchan(8), inn.conf(5), innd(8), newsfeeds(5), pgpverify(8), sh(1).
197
198 =cut