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).