chiark / gitweb /
option for no inotify; manpage fix
[innduct.git] / doc / man / control.ctl.5
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings.  \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
32 .tr \(*W-
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 .    ds -- \(*W-
36 .    ds PI pi
37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
39 .    ds L" ""
40 .    ds R" ""
41 .    ds C` ""
42 .    ds C' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .if \nF \{\
56 .    de IX
57 .    tm Index:\\$1\t\\n%\t"\\$2"
58 ..
59 .    nr % 0
60 .    rr F
61 .\}
62 .\"
63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
65 .hy 0
66 .if n .na
67 .\"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
70 .    \" fudge factors for nroff and troff
71 .if n \{\
72 .    ds #H 0
73 .    ds #V .8m
74 .    ds #F .3m
75 .    ds #[ \f1
76 .    ds #] \fP
77 .\}
78 .if t \{\
79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 .    ds #V .6m
81 .    ds #F 0
82 .    ds #[ \&
83 .    ds #] \&
84 .\}
85 .    \" simple accents for nroff and troff
86 .if n \{\
87 .    ds ' \&
88 .    ds ` \&
89 .    ds ^ \&
90 .    ds , \&
91 .    ds ~ ~
92 .    ds /
93 .\}
94 .if t \{\
95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101 .\}
102 .    \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 .    \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 .    \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
117 \{\
118 .    ds : e
119 .    ds 8 ss
120 .    ds o a
121 .    ds d- d\h'-1'\(ga
122 .    ds D- D\h'-1'\(hy
123 .    ds th \o'bp'
124 .    ds Th \o'LP'
125 .    ds ae ae
126 .    ds Ae AE
127 .\}
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
130 .\"
131 .IX Title "CONTROL.CTL 5"
132 .TH CONTROL.CTL 5 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
133 .SH "NAME"
134 control.ctl \- Specify handling of Usenet control messages
135 .SH "DESCRIPTION"
136 .IX Header "DESCRIPTION"
137 \&\fIcontrol.ctl\fR in \fIpathetc\fR is used to determine what action is taken
138 when a control message is received.  It is read by \fBcontrolchan\fR, which
139 is normally invoked as a channel program by \fBinnd\fR.  When \fIcontrol.ctl\fR
140 is modified, \fBcontrolchan\fR notices this automatically and reloads it.
141 .PP
142 Blank lines and lines beginning with a number sign (\f(CW\*(C`#\*(C'\fR) are ignored.
143 All other lines should consist of four fields separated by colons:
144 .PP
145 .Vb 1
146 \&    <type>:<from>:<newsgroups>:<action>
147 .Ve
148 .PP
149 The first field, <type>, is the type of control message for which this
150 line is valid.  It should either be the name of a control message or the
151 word \f(CW\*(C`all\*(C'\fR to indicate that it applies to all control messages.
152 .PP
153 The second field, <from>, is a shell-style pattern that matches the e\-mail
154 address of the person posting the message (with the address first
155 converted to lowercase).  The matching is done with rules equivalent to
156 those of the shell's \fIcase\fR statement; see \fIsh\fR\|(1) for more details.
157 .PP
158 If the control message is a newgroup or rmgroup, the third field,
159 <newsgroups>, is a shell-style pattern matching the newsgroup affected by
160 the control message.  If the control message is a checkgroups, the third
161 field is a shell-style pattern matching the newsgroups that should be
162 processed for checking.  If the control message is of any other type, the
163 third field is ignored.
164 .PP
165 The fourth field, <action>, specifies what action to take with control
166 messages that match this line.  The following actions are understood:
167 .IP "\fBdoit\fR" 4
168 .IX Item "doit"
169 The action requested by the control message should be performed.  For
170 checkgroups messages, this means that the shell commands that should
171 be run will be mailed to the news administrator (the argument to
172 \&\fB\-\-with\-news\-master\fR given at configure time, \f(CW\*(C`usenet\*(C'\fR by default); for
173 other commands, this means that the change will be silently performed.  If
174 you always want notification of actions taken, use \f(CW\*(C`doit=mail\*(C'\fR instead (see
175 below).
176 .IP "\fBdoifarg\fR" 4
177 .IX Item "doifarg"
178 If the control message has an argument, this is equivalent to \fBdoit\fR.  If
179 it does not have an argument, this is equivalent to \fBmail\fR.  This is only
180 useful for entries for sendsys control messages, allowing a site to
181 request its own \fInewsfeeds\fR entry by posting a \f(CW\*(C`sendsys mysite\*(C'\fR control
182 message, but not allowing the entire \fInewsfeeds\fR file to be sent.  This
183 was intended to partially counter so-called \*(L"sendsys bombs,\*(R" where forged
184 sendsys control messages were used to mailbomb people.
185 .Sp
186 Processing sendsys control messages is not recommended even with this
187 work-around unless they are authenticated in some fashion.  The risk of
188 having news servers turned into anonymous mail bombing services is too
189 high.
190 .IP "\fBdoit\fR=\fIfile\fR" 4
191 .IX Item "doit=file"
192 The action is performed as in \fBdoit\fR, and additionally a log entry is
193 written to the specified log file \fIfile\fR.  If \fIfile\fR is the word
194 \&\f(CW\*(C`mail\*(C'\fR, the log entry is mailed to the news administrator instead.  An
195 empty string is equivalent to \fI/dev/null\fR and says to log nothing.
196 .Sp
197 If \fIfile\fR starts with a slash, it is taken as the absolute filename to
198 use for the log file.  Otherwise, the filename is formed by prepending
199 \&\fIpathlog\fR and a slash and appending \f(CW\*(C`.log\*(C'\fR.  In other words, an action
200 of \f(CW\*(C`doit=newgroup\*(C'\fR will log to \fIpathlog\fR/newgroup.log.
201 .IP "\fBdrop\fR" 4
202 .IX Item "drop"
203 No action is taken and the message is ignored.
204 .IP "\fBverify\-*\fR" 4
205 .IX Item "verify-*"
206 If the action starts with the string \f(CW\*(C`verify\-\*(C'\fR, as in:
207 .Sp
208 .Vb 1
209 \&    verify\-news.announce.newgroups
210 .Ve
211 .Sp
212 then \s-1PGP\s0 verification of the control message will be done and the user \s-1ID\s0
213 of the key of the authenticated signer will be checked against the
214 expected identity defined by the rest of the string
215 (\f(CW\*(C`news.announce.newgroups\*(C'\fR in the above example.  This verification is
216 done via \fBpgpverify\fR; see \fIpgpverify\fR\|(8) for more details.
217 .Sp
218 If no logging is specified (with =\fIfile\fR as mentioned below), logging will
219 be done the same as with \fBdoit\fR as described above.
220 .IP "\fBverify\-*\fR=\fBmail\fR" 4
221 .IX Item "verify-*=mail"
222 \&\s-1PGP\s0 verification is done as for the \fBverify\-*\fR action described above, and
223 notification of successful newgroup and rmgroup control messages and the
224 output of checkgroups messages will be mailed to the news administrator.
225 (In the case of checkgroups messages, this means that the shell script that
226 should be run will be mailed to the administrator.)
227 .IP "\fBverify\-*\fR=\fIfile\fR" 4
228 .IX Item "verify-*=file"
229 \&\s-1PGP\s0 verification is done as for the \fBverify\-*\fR action described above,
230 and a log entry is written to the specified file as described in
231 \&\fBdoit\fR=\fIfile\fR above.  (In the case of checkgroups messages, this means
232 that the shell script output of the checkgroups message will be written to
233 that file.)
234 .IP "\fBlog\fR" 4
235 .IX Item "log"
236 A one-line log message is sent to standard error.  \fBinnd\fR normally
237 directs this to \fIpathlog\fR/errlog.
238 .IP "\fBlog\fR=\fIfile\fR" 4
239 .IX Item "log=file"
240 A log entry is written to the specified log file, which is interpreted as
241 in \fBdoit\fR=\fIfile\fR described above.
242 .IP "\fBmail\fR" 4
243 .IX Item "mail"
244 A mail message is sent to the news administrator without taking any other
245 action.
246 .PP
247 Processing of a checkgroups message will never actually change the
248 \&\fIactive\fR file (the list of groups carried by the server).  The difference
249 between a \fBdoit\fR or \fBverify\fR action and a \fBmail\fR action for a
250 checkgroups control message lies only in what e\-mail is sent; \fBdoit\fR or
251 \&\fBverify\fR will mail the news administrator a shell script to create,
252 delete, or modify newsgroups to match the checkgroups message, whereas
253 \&\fBmail\fR will just mail the entire message.  In either case, the news
254 administrator will have to take action to implement the checkgroups
255 message, and if that mail is ignored, nothing will be changed.
256 .PP
257 Lines are matched in order and the last matching line in the file will be
258 used.
259 .PP
260 Use of the \fBverify\fR action for processing newgroup, rmgroup, and
261 checkgroups messages is \s-1STRONGLY\s0 recommended.  Abuse of control messages
262 is rampant, and authentication via \s-1PGP\s0 signature is currently the only
263 reliable way to be sure that a control message comes from who it claims to
264 be from.  Most major hierarchies are now issuing PGP-authenticated control
265 messages.
266 .PP
267 In order to use \fBverify\fR actions, the \s-1PGP\s0 key ring of the news user must
268 be populated with the \s-1PGP\s0 keys of the hierarchy maintainers whose control
269 messages you want to honor.  For more details on PGP-authenticated control
270 messages and the \s-1URL\s0 for downloading the \s-1PGP\s0 keys of major hierarchies,
271 see \fIpgpverify\fR\|(8).
272 .PP
273 Control messages of type cancel are handled internally by \fBinnd\fR and
274 cannot be affected by any of the mechanisms described here.
275 .SH "EXAMPLE"
276 .IX Header "EXAMPLE"
277 With the following three lines in \fIcontrol.ctl\fR:
278 .PP
279 .Vb 3
280 \&    newgroup:*:*:drop
281 \&    newgroup:group\-admin@isc.org:comp.*:verify\-news.announce.newgroups
282 \&    newgroup:kre@munnari.oz.au:aus.*:mail
283 .Ve
284 .PP
285 a newgroup coming from \f(CW\*(C`group\-admin@isc.org\*(C'\fR will be honored if it is for
286 a newsgroup in the comp.* hierarchy and if it has a valid signature
287 corresponding to the \s-1PGP\s0 key with a user \s-1ID\s0 of \f(CW\*(C`news.announce.newgroups\*(C'\fR.
288 If any newgroup claiming to be from \f(CW\*(C`kre@munnari.oz.au\*(C'\fR for a newsgroup
289 in the aus.* hierarchy is received, it too will be honored.  All other
290 newgroup messages will be ignored.
291 .SH "WARNINGS"
292 .IX Header "WARNINGS"
293 The third argument for a line affecting checkgroups does \fBnot\fR affect
294 whether the line matches.  It is only used after a matching line is found,
295 to filter out which newsgroups listed in the checkgroups will be
296 processed.  This means that a line like:
297 .PP
298 .Vb 1
299 \&    checkgroups:*:*binaries*:drop
300 .Ve
301 .PP
302 will cause \fBall\fR checkgroups control messages to be dropped unless they
303 match a line after this one in \fIcontrol.ctl\fR, not just ignore newsgroups
304 containing \f(CW\*(C`binaries\*(C'\fR in the name.  The general rule is to never use \f(CW\*(C`*\*(C'\fR
305 in the second field for a line matching checkgroups messages.  There is
306 unfortunately no way to do what the author of a line like the above
307 probably intended to do (yet).
308 .SH "HISTORY"
309 .IX Header "HISTORY"
310 Written by Rich \f(CW$alz\fR <rsalz@uunet.uu.net> for InterNetNews.  Rewritten in
311 \&\s-1POD\s0 by Russ Allbery <rra@stanford.edu>.
312 .PP
313 $Id: control.ctl.5 7880 2008-06-16 20:37:13Z iulius $
314 .SH "SEE ALSO"
315 .IX Header "SEE ALSO"
316 \&\fIcontrolchan\fR\|(8), \fIinn.conf\fR\|(5), \fIinnd\fR\|(8), \fInewsfeeds\fR\|(5), \fIpgpverify\fR\|(8), \fIsh\fR\|(1).