X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;ds=sidebyside;f=doc%2Fman%2Fcontrol.ctl.5;fp=doc%2Fman%2Fcontrol.ctl.5;h=0000000000000000000000000000000000000000;hb=b7a32e2d73e3ab1add8208d3e157f7269a31ef4d;hp=fe4f120029eb51c535522cb5084bcb82efe09a6b;hpb=ac902a8299ff4469b356836f431ead31c3377377;p=innduct.git diff --git a/doc/man/control.ctl.5 b/doc/man/control.ctl.5 deleted file mode 100644 index fe4f120..0000000 --- a/doc/man/control.ctl.5 +++ /dev/null @@ -1,316 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.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" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" 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 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation" -.SH "NAME" -control.ctl \- Specify handling of Usenet control messages -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fIcontrol.ctl\fR in \fIpathetc\fR 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 -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 -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. -.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. 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. For -checkgroups messages, this means that the shell commands that should -be run will 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); for -other commands, this means that the change will be silently performed. 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. -.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.) -.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.) -.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 -Processing of a checkgroups message will never actually change the -\&\fIactive\fR file (the list of groups carried by the server). The difference -between a \fBdoit\fR or \fBverify\fR action and a \fBmail\fR action for a -checkgroups control message lies only in what e\-mail is sent; \fBdoit\fR or -\&\fBverify\fR will mail the news administrator a shell script to create, -delete, or modify newsgroups to match the checkgroups message, whereas -\&\fBmail\fR will just mail the entire message. In either case, the news -administrator will have to take action to implement the checkgroups -message, and if that mail is ignored, nothing will be changed. -.PP -Lines are matched in order and the last matching line in the file will be -used. -.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 honor. 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 "EXAMPLE" -.IX Header "EXAMPLE" -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 honored 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 honored. All other -newgroup messages will be ignored. -.SH "WARNINGS" -.IX Header "WARNINGS" -The third argument for a line affecting checkgroups does \fBnot\fR affect -whether the line matches. It is only used after a matching line is found, -to filter out which newsgroups listed in the checkgroups will be -processed. This means that a line like: -.PP -.Vb 1 -\& checkgroups:*:*binaries*:drop -.Ve -.PP -will cause \fBall\fR checkgroups control messages to be dropped unless they -match a line after this one in \fIcontrol.ctl\fR, not just ignore newsgroups -containing \f(CW\*(C`binaries\*(C'\fR in the name. The general rule is to never use \f(CW\*(C`*\*(C'\fR -in the second field for a line matching checkgroups messages. There is -unfortunately no way to do what the author of a line like the above -probably intended to do (yet). -.SH "HISTORY" -.IX Header "HISTORY" -Written by Rich \f(CW$alz\fR for InterNetNews. Rewritten in -\&\s-1POD\s0 by Russ Allbery . -.PP -$Id: control.ctl.5 7880 2008-06-16 20:37:13Z iulius $ -.SH "SEE ALSO" -.IX Header "SEE ALSO" -\&\fIcontrolchan\fR\|(8), \fIinn.conf\fR\|(5), \fIinnd\fR\|(8), \fInewsfeeds\fR\|(5), \fIpgpverify\fR\|(8), \fIsh\fR\|(1).