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