.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "CONTROL.CTL 5" .TH CONTROL.CTL 5 "2018-05-14" "INN 2.6.3" "InterNetNews Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" control.ctl \- Specify handling of Usenet control messages .SH "DESCRIPTION" .IX Header "DESCRIPTION" The file \fIpathetc\fR/control.ctl is used to determine what action is taken when a control message is received. It is read by \fBcontrolchan\fR, which is normally invoked as a channel program by \fBinnd\fR. When \fIcontrol.ctl\fR is modified, \fBcontrolchan\fR notices this automatically and reloads it. .PP If a \fIcontrol.ctl.local\fR file exists in \fIpathetc\fR, it is read by \&\fBcontrolchan\fR after \fIcontrol.ctl\fR (the resulting behaviour is as though the contents of \fIcontrol.ctl.local\fR were at the end of \&\fIcontrol.ctl\fR). This local file is formatted like \fIcontrol.ctl\fR and is intended to contain local customization. It is also automatically reloaded when modified. .PP Blank lines and lines beginning with a number sign (\f(CW\*(C`#\*(C'\fR) are ignored. All other lines should consist of four fields separated by colons: .PP .Vb 1 \& ::: .Ve .PP Lines are matched in order and the last matching line in the file will be used, except for checkgroups messages which are handled differently (every matching line is used). .PP The first field, , is the type of control message for which this line is valid. It should either be the name of a control message or the word \f(CW\*(C`all\*(C'\fR to indicate that it applies to all control messages. Besides, the following special types are understood: .IP "\fB/encoding/\fR" 4 .IX Item "/encoding/" This type specifies the encoding of newgroup and checkgroups control messages so that new descriptions could be decoded the right way. .Sp .Vb 1 \& /encoding/:*:cn.*:gb18030 .Ve .Sp means that a description for a newsgroup in the Chinese cn.* hierarchy will be decoded as though it were encoded in \s-1GB18030,\s0 unless a charset is specified in the control message (in such a case, the charset mentioned in the message is used). However, it is possible to override the mentioned charset if \f(CW\*(C`=force\*(C'\fR is appended after the encoding. For instance, .Sp .Vb 1 \& /encoding/:*:scout.forum.chinese:big5=force .Ve .Sp means that the description for scout.forum.chinese will always be decoded as though it were encoded in Big5, no matter the charset of the corresponding control message. .Sp The default value when no encoding is mentioned (or when the specified encoding is unknown) is \f(CW\*(C`CP1252\*(C'\fR. .Sp The last matching line for a given newsgroup name in \fIcontrol.ctl\fR will be used. .IP "\fB/localencoding/\fR" 4 .IX Item "/localencoding/" When this type is used, the line consist of only two fields. The default value when this type does not appear in \fIcontrol.ctl\fR (or when the specified charset is unknown) is equivalent to: .Sp .Vb 1 \& /localencoding/:utf\-8 .Ve .Sp It means that new descriptions in the \fInewsgroups\fR file will be written using \s-1UTF\-8. \s0 And \fBcontrolchan\fR will try to read existing descriptions, so as to see whether they should be updated, as though they were encoded in \s-1UTF\-8.\s0 .Sp The last matching line in \fIcontrol.ctl\fR will be used. .IP "\fB/maxdocheckgroups/\fR" 4 .IX Item "/maxdocheckgroups/" This type specifies the maximum number of changes that could be made at one time by a checkgroups before bailing and mailing the changes to the admin if no log file was specified. The default value is \f(CW10\fR. .Sp .Vb 2 \& /maxdocheckgroups/:*:*:10 \& /maxdocheckgroups/:*:fr.*:20 .Ve .Sp Such a configuration means that a checkgroups containing 15 changes for the French fr.* hierarchy (newgroups to add, remove or change the status) will be automatically honoured whereas a checkgroups containing 15 changes for france.* will only have the required changes mailed or logged. .Sp The last matching line for a given newsgroup name in \fIcontrol.ctl\fR will be used. .PP The second field, , is a shell-style pattern that matches the e\-mail address of the person posting the message (with the address first converted to lowercase). The matching is done with rules equivalent to those of the shell's \fIcase\fR statement; see \fIsh\fR\|(1) for more details. .PP If the control message is a newgroup or rmgroup, the third field, , is a shell-style pattern matching the newsgroup affected by the control message (especially \f(CW\*(C`?\*(C'\fR matches exactly one character, \&\f(CW\*(C`*\*(C'\fR matches zero or more characters and \f(CW\*(C`|\*(C'\fR permits matching several patterns on the same line \-\-\ for instance \f(CW\*(C`comp.*|humanities.*\*(C'\fR matches every newsgroup whose name begins with \f(CW\*(C`comp.\*(C'\fR or \f(CW\*(C`humanities.\*(C'\fR). If the control message is a checkgroups, the third field is a shell-style pattern matching the newsgroups that should be processed for checking. If the control message is of any other type, the third field is ignored. .PP The fourth field, , specifies what action to take with control messages that match this line. The following actions are understood: .IP "\fBdoit\fR" 4 .IX Item "doit" The action requested by the control message should be performed. It means that the change will be silently performed. For checkgroups messages, depending on the value of \fB/maxdocheckgroups/\fR, the shell commands that should be run may be mailed to the news administrator (the argument to \&\fB\-\-with\-news\-master\fR given at configure time, \f(CW\*(C`usenet\*(C'\fR by default) instead of being performed. .Sp If you always want notification of actions taken, use \f(CW\*(C`doit=mail\*(C'\fR instead (see below). .IP "\fBdoifarg\fR" 4 .IX Item "doifarg" If the control message has an argument, this is equivalent to \fBdoit\fR. If it does not have an argument, this is equivalent to \fBmail\fR. This is only useful for entries for sendsys control messages, allowing a site to request its own \fInewsfeeds\fR entry by posting a \f(CW\*(C`sendsys mysite\*(C'\fR control message, but not allowing the entire \fInewsfeeds\fR file to be sent. This was intended to partially counter so-called \*(L"sendsys bombs\*(R", where forged sendsys control messages were used to mailbomb people. .Sp Processing sendsys control messages is not recommended even with this work-around unless they are authenticated in some fashion. The risk of having news servers turned into anonymous mail bombing services is too high. .IP "\fBdoit\fR=\fIfile\fR" 4 .IX Item "doit=file" The action is performed as in \fBdoit\fR, and additionally a log entry is written to the specified log file \fIfile\fR. If \fIfile\fR is the word \&\f(CW\*(C`mail\*(C'\fR, the log entry is mailed to the news administrator instead. An empty string is equivalent to \fI/dev/null\fR and says to log nothing. .Sp If \fIfile\fR starts with a slash, it is taken as the absolute filename to use for the log file. Otherwise, the filename is formed by prepending \&\fIpathlog\fR and a slash, and appending \f(CW\*(C`.log\*(C'\fR. In other words, an action of \f(CW\*(C`doit=newgroup\*(C'\fR will log to \fIpathlog\fR/newgroup.log. .IP "\fBdrop\fR" 4 .IX Item "drop" No action is taken and the message is ignored. For checkgroups messages, it means that the newsgroups mentioned will be considered as not existent in the checkgroups for its subsequent process. .Sp .Vb 2 \& checkgroups:*:comp.*:doit \& checkgroups:*:*binaries*:drop .Ve .Sp will for instance remove every newsgroup whose name contains \f(CW\*(C`binaries\*(C'\fR in the comp.* hierarchy, even though such groups are mentioned in the checkgroups. (In that example, the removal is performed by the \fBdoit\fR action because \fBdrop\fR does nothing by itself.) .IP "\fBverify\-*\fR" 4 .IX Item "verify-*" If the action starts with the string \f(CW\*(C`verify\-\*(C'\fR, as in: .Sp .Vb 1 \& verify\-news.announce.newgroups .Ve .Sp then \s-1PGP\s0 verification of the control message will be done and the user \s-1ID\s0 of the key of the authenticated signer will be checked against the expected identity defined by the rest of the string (\f(CW\*(C`news.announce.newgroups\*(C'\fR in the above example). This verification is done via \fBpgpverify\fR; see \fIpgpverify\fR\|(8) for more details. .Sp If no logging is specified (with =\fIfile\fR as mentioned below), logging will be done the same as with \fBdoit\fR as described above. .IP "\fBverify\-*\fR=\fBmail\fR" 4 .IX Item "verify-*=mail" \&\s-1PGP\s0 verification is done as for the \fBverify\-*\fR action described above, and notification of successful newgroup and rmgroup control messages and the output of checkgroups messages will be mailed to the news administrator. (In the case of checkgroups messages, this means that the shell script that should be run will be mailed to the administrator. The subject of the mail will contain information on whether the script has already been run, depending on the value of \fB/maxdocheckgroups/\fR.) .IP "\fBverify\-*\fR=\fIfile\fR" 4 .IX Item "verify-*=file" \&\s-1PGP\s0 verification is done as for the \fBverify\-*\fR action described above, and a log entry is written to the specified file as described in \&\fBdoit\fR=\fIfile\fR above. (In the case of checkgroups messages, this means that the shell script output of the checkgroups message will be written to that file. The initial line of the log will contain information on whether the script has already been run, depending on the value of \&\fB/maxdocheckgroups/\fR.) .IP "\fBlog\fR" 4 .IX Item "log" A one-line log message is sent to standard error. \fBinnd\fR normally directs this to \fIpathlog\fR/errlog. .IP "\fBlog\fR=\fIfile\fR" 4 .IX Item "log=file" A log entry is written to the specified log file, which is interpreted as in \fBdoit\fR=\fIfile\fR described above. .IP "\fBmail\fR" 4 .IX Item "mail" A mail message is sent to the news administrator without taking any other action. .PP One of the difference between a \fBdoit\fR or \fBverify\fR action and a \fBmail\fR action for a checkgroups control message lies in what e\-mail is sent; \fBdoit\fR or \fBverify\fR will mail the news administrator a shell script (which may have already been run) to create, delete, or modify newsgroups to match the checkgroups message, whereas \fBmail\fR will just mail relevant lines of the checkgroups for manual processing by the news administrator. .PP Use of the \fBverify\fR action for processing newgroup, rmgroup and checkgroups messages is \s-1STRONGLY\s0 recommended. Abuse of control messages is rampant, and authentication via \s-1PGP\s0 signature is currently the only reliable way to be sure that a control message comes from who it claims to be from. Most major hierarchies are now issuing PGP-authenticated control messages. .PP In order to use \fBverify\fR actions, the \s-1PGP\s0 key ring of the news user must be populated with the \s-1PGP\s0 keys of the hierarchy maintainers whose control messages you want to honour. For more details on PGP-authenticated control messages and the \s-1URL\s0 for downloading the \s-1PGP\s0 keys of major hierarchies, see \fIpgpverify\fR\|(8). .PP Control messages of type cancel are handled internally by \fBinnd\fR and cannot be affected by any of the mechanisms described here. .SH "EXAMPLES" .IX Header "EXAMPLES" With the following three lines in \fIcontrol.ctl\fR: .PP .Vb 3 \& newgroup:*:*:drop \& newgroup:group\-admin@isc.org:comp.*:verify\-news.announce.newgroups \& newgroup:kre@munnari.oz.au:aus.*:mail .Ve .PP a newgroup coming from \f(CW\*(C`group\-admin@isc.org\*(C'\fR will be honoured if it is for a newsgroup in the comp.* hierarchy and if it has a valid signature corresponding to the \s-1PGP\s0 key with a user \s-1ID\s0 of \f(CW\*(C`news.announce.newgroups\*(C'\fR. If any newgroup claiming to be from \f(CW\*(C`kre@munnari.oz.au\*(C'\fR for a newsgroup in the aus.* hierarchy is received, it too will be honoured. All other newgroup messages will be ignored. .PP Besides, if a \fIcontrol.ctl.local\fR file exists and contains: .PP .Vb 1 \& newgroup:*:comp.lang.*:drop .Ve .PP then a newgroup control article for comp.lang.awk will not be honoured even though it comes from \f(CW\*(C`group\-admin@isc.org\*(C'\fR with a valid signature. .PP As for checkgroups, suppose your news server contains these groups for foo.*, all of them being unmoderated (\f(CW\*(C`y\*(C'\fR status in the \fIactive\fR file): .PP .Vb 8 \& foo.bar1 \& foo.bar2.first \& foo.bar2.second \& foo.bar2.third \& foo.bar3 \& foo.bar3.first \& foo.bar3.second \& foo.bar5 .Ve .PP and you receive the following checkgroups by for foo.*: .PP .Vb 5 \& foo.bar1 A valid newsgroup. \& foo.bar3.first Only one newsgroup in foo.bar3.*. \& foo.bar4 A newsgroup you want. \& foo.bar5 A newsgroup you do not want. \& foo.bar5.first Another newsgroup you do not want. .Ve .PP with the following \fIcontrol.ctl\fR entries: .PP .Vb 1 \& /maxdocheckgroups/:*:foo.*:2 \& \& checkgroups:foo@bar.com:foo.*:verify\-key\-foo \& checkgroups:foo@bar.com:foo.bar2.*:doit \& checkgroups:foo@bar.com:foo.bar3.*:mail \& checkgroups:foo@bar.com:foo.bar4|foo.bar4.*:doit \& checkgroups:foo@bar.com:foo.bar5|foo.bar5.*:drop .Ve .PP Then, as \fIcontrol.ctl\fR is processed from bottom, here is what happens: .IP "1." 4 The newsgroups foo.bar5 and foo.bar5.first are marked as unwanted. But nothing is done yet: other \fIcontrol.ctl\fR entries have to be processed with a real action and a set of newsgroups containing foo.bar5 and foo.bar5.first. .IP "2." 4 The newsgroup foo.bar4 is silently created on the news server, with the description \*(L"A newsgroup you want.\*(R" added to the \fInewsgroups\fR file. In the absence of encoding values (either in the checkgroups message or in \fB/encoding/\fR and \fB/localencoding\fR), the default is to decode the sentence as \s-1CP1242\s0 and re-encode it as \s-1UTF\-8.\s0 .Sp If \f(CW\*(C`doit=mail\*(C'\fR was used, a mail would be sent to the news administrator to inform him that foo.bar4 was successfully created. .IP "3." 4 The newsgroup foo.bar3.second is no longer present. A mail is sent to the news administrator with a shell script to execute. When it is manually executed, foo.bar3.second will be removed. .Sp Note that the descriptions are handled differently and have already been updated without any manual intervention (foo.bar3.first now has the description \*(L"Only one newsgroup in foo.bar3.*.\*(R" and foo.bar3.second no longer has a description). .IP "4." 4 The newsgroups foo.bar2.first, foo.bar2.second and foo.bar2.third are no longer present. However, as the maximum number of changes that could be made at one time by a checkgroups before bailing and mailing the changes to the news administrator is 2, these newsgroups are not removed. A mail is sent with a shell script to manually execute in order to remove these groups from the news server. .Sp Note that their descriptions are removed from the \fInewsgroups\fR file, as well as any other possible descriptions for obsolete newsgroups in foo.bar2.*. .IP "5." 4 The remaining entry is executed if the \s-1PGP\s0 verification of the checkgroups message is successful. Otherwise, nothing is done (especially, foo.bar5 remains on the news server). .Sp In case the \s-1PGP\s0 signature is verified, foo.bar3 and foo.bar5 are removed from the news server. This entry acts upon newsgroups marked as dropped in its scope and newsgroups not already dealt with by previous \fIcontrol.ctl\fR entries (like foo.bar3 because only foo.bar3.* was previously checked). .Sp Note that if you had wanted to keep foo.bar3 or foo.bar5, you could have added them to the \fIlocalgroups\fR file in \fIpathetc\fR. .SH "HISTORY" .IX Header "HISTORY" Written by Rich \f(CW$alz\fR for InterNetNews. Rewritten in \&\s-1POD\s0 by Russ Allbery . .PP \&\f(CW$Id:\fR control.ctl.pod 10283 2018\-05\-14 12:43:05Z iulius $ .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIcontrolchan\fR\|(8), \fIinn.conf\fR\|(5), \fIinnd\fR\|(8), \fInewsfeeds\fR\|(5), \fInewsgroups\fR\|(5), \&\fIpgpverify\fR\|(8), \fIsh\fR\|(1).