Index: control/pgpverify.in =================================================================== RCS file: /dist1/cvs/isc/inn/inn/control/pgpverify.in,v retrieving revision 1.5 diff -u -r1.5 pgpverify.in --- control/pgpverify.in 2002/11/25 22:36:01 1.5 +++ control/pgpverify.in 2002/12/03 04:42:52 @@ -695,7 +695,7 @@ the control message, not the name and address that appear in the control message's From or Sender headers. -Thus, using the B and B programs appropriately +Thus, appropriate use of the B and B programs essentially eliminates the possibility of malicious users forging Usenet control messages that sites will act upon, as such users would have to obtain the PGP private key in order to forge a control message that would Index: doc/man/actsync.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/actsync.8,v retrieving revision 1.16 diff -u -r1.16 actsync.8 --- doc/man/actsync.8 2002/08/10 18:51:31 1.16 +++ doc/man/actsync.8 2002/12/03 04:42:54 @@ -3,7 +3,7 @@ .\" Copyright (c) Landon Curt Noll, 1993. .\" All rights reserved. .\" -.\" Permission to use and modify is hereby granted so long as this +.\" Permission to use and modify is hereby granted so long as this .\" notice remains. Use at your own risk. No warranty is implied. .\" .\" @(#) $Id: actsync.8,v 1.16 2002/08/10 18:51:31 rra Exp $ @@ -20,7 +20,7 @@ .br [\fB\-n\fP\fI name\fP] [\fB\-o\fP\fI fmt\fP] [\fB\-p\fP\fI min_%_unchg\fP] [\fB\-q\fP\fI hostid\fP] .br - [\fB\-s\fP\fI size\fP] [\fB\-t\fP\fI hostid\fP] [\fB\-T\fP] [\fB\-v\fP\fI verbose_lvl\fP] + [\fB\-s\fP\fI size\fP] [\fB\-t\fP\fI hostid\fP] [\fB\-T\fP] [\fB\-v\fP\fI verbosity\fP] .br [\fB\-z\fP\fI sec\fP] [\fIhost1\fP] \fIhost2\fP .sp 1 @@ -28,10 +28,10 @@ [\fB\-x\fP] \fIactsync.cfg\fP [\fIdebug_level\fP [\fIdebug_outfmt\fP] ] .SH DESCRIPTION .IR Actsync (8) -permits one to synchronize, compare or merge two -.IR active (5) +permits one to synchronize, compare, or merge two +.I active files. -With this utility one may add, change or remove newsgroups on the +With this utility one may add, change, or remove newsgroups on the local news server to make it similar to the list the newsgroups found on another system or file. The synchronization need not be exact. @@ -50,37 +50,37 @@ may fail to reach your site. .sp 1 Your -.IR control.ctl (5) -is out of date or incomplete. +.I control.ctl +may be out of date or incomplete. .sp 1 -News articles for a new newsgroup arrive ahead (sometimes days ahead) +News articles for a new newsgroup can arrive ahead (sometimes days ahead) of the control message. .sp 1 Control messages may be forged, thus bypassing the restrictions found in -.IR control.ctl (5). +.I control.ctl . .sp 1 Your -.IR active (5) +.I active file may have been trashed. .sp 1 .in -0.5i .PP -If either +If .I host1 or .I host2 -begin with a +begins with a .B ``.'' or .BR ``/'' , -then they assumed to be a name of a file containing information in the +then it is assumed to be a name of a file containing information in the .IR active (5) format. The .IR getlist (1) -utility may be used to obtain copy a remote system's active file -via its NNTP server, or an FTP client program can get retrieve such a +utility may be used to obtain copy a remote system's active file +via its NNTP server, or an FTP client program can retrieve such a file from an FTP archive (such as ftp://ftp.isc.org/pub/usenet/CONFIG/active; see more about this below). Newsgroup information from a file @@ -102,10 +102,10 @@ will attempt to use the .B NNTP protocol to obtain a copy of the the specified system's active file. -If the host argument contains a +If the host argument contains a .B ``:'' , the right side will be considerd the port to connect to on the remote system. -If no port number ist specified, +If no port number is specified, .IR actsync (8) will connect to port 119. .PP @@ -115,20 +115,20 @@ remain the same. .PP If only one host is specified, it is assumed to be -.IR host2 . -If -.IR host1 , +.IR host2 ; +if +.IR host1 is not specified, it assumed to be the default local NNTP server as specified by the .B NNTPSERVER environment variable, or by the .B server value found in -.IR inn.conf (5). +.IR inn.conf . .PP -The newsgroup synchronization by default, involves all newsgroups +The newsgroup synchronization, by default, involves all newsgroups found on both hosts. -One may also synchronize on a subset of newsgroups by directing +One may also synchronize a subset of newsgroups by directing .IR actsync (8) to ignore certain newsgroups from both systems. .PP @@ -137,7 +137,7 @@ daemon provides a convenient interface to configure and run .IR actsync (8). If a host is not initially reachable, -the daemon will thrice retry 9 times, waiting 6 minutes before +the daemon will retry up to 9 additional times, waiting 6 minutes before each retry. This daemon runs in the foreground, sending output to standard output and standard error. @@ -145,17 +145,15 @@ If the \fB\-x\fP flag is given to .IR actsyncd (8), then a -.IR ctlinnd xexec +.IR ctlinnd\ xexec will be used instead of a -.IR ctlinnd reload +.IR ctlinnd\ reload to load the newly modified active file. .PP -The configuration filename for the daemon is given in the -.I actsync.cfg -argument. -The -.I actsync.cfg -file understands the following options: +The configuration filename for the daemon is given as a +commandline argument, usually +.I /actsync.cfg +The config file can contain the following options: .sp 1 .in +0.5i .nf @@ -163,33 +161,34 @@ \fBftppath=\fP\fI/remote/path/to/active/file\fP \fBspool=\fP\fI\fP \fBignore_file=\fP\fIignore_file\fP -\fBflags=\fP\fIactsyncd\fP (8) options +\fBflags=\fP\fIactsyncd\fP(8) options .fi .in -0.5i .sp 1 -The \fBhost\fP, \fBignore_file\fP and \fBflags\fP lines are mandatory. +The \fBhost\fP, \fBignore_file\fP, and \fBflags\fP lines are mandatory. .sp 1 The keyword must start at the beginning of the line, and there may be no whitespace before the .B ``='' character. Blank lines are ignored. -Comments start with +Comment lines start with .B ``#'' and are ignored. -All other lines may produce undefined results. +Any other lines may produce undefined results. .sp 1 -The \fBhost\fP config file line refers to the \fIhost2\fP value to sync off of. +The \fBhost\fP config file line refers to the \fIhost2\fP parameter to +.IR actsync (8). The \fBftppath\fP directive causes the machine named in the \fBhost\fP line to accessed as an ftp server, retrieving the file named. If the filename ends in \fB.gz\fP or \fB.Z\fP, then it will automatically be uncompressed after retrieval. -The \fBspool\fP config file lines determines where top the +The \fBspool\fP config file lines determines where the top of the news spool tree is to be found. The \fBignore_file\fP config file line names the ignore file to be used by .IR actsync (8). -The \fBflags\fP config file line refers to all flags that you wish to pass to +The \fBflags\fP config file line contains any flags that you wish to pass to .IR actsync (8). .sp 1 Note that the \fB\-i ignore_file\fP option @@ -202,7 +201,8 @@ and \fI/pub/usenet/CONFIG/active\fP for \fBftppath\fP. You can read about the policies used for maintaining that active file at \fIftp://ftp.isc.org/pub/usenet/CONFIG/README\fP. Consider -sychronizing from this file on a daily basis by using \fIcron\fP. +sychronizing from this file on a daily basis by using +.IR cron (8). .SH OPTIONS The options to .IR actsync (8) @@ -243,8 +243,8 @@ .in -0.5i .sp 1 The default is -.BR "\-b 0" , -no bork newsgroups are ignored. +.BR "\-b 0" ; +no newsgroups are ignored because of bork-style names. .TP .BI \-d " hostid" This flag causes @@ -266,8 +266,10 @@ .in -0.5i .sp 1 The newsgroups directory of a newsgroups with a all numeric component -could conflict with an article from another group. -For example, the directory for the first newsgroup listed above +could conflict with an article from another group if stored using the +``tradspool'' storage method; see +.IR storage.conf (5). +For example, the directory for the first newsgroup listed above is the same path as article number 23209 from the newsgroup: .sp .in +0.5i @@ -277,7 +279,7 @@ .in -0.5i .sp 1 The default is -.BR "\-d 0" , +.BR "\-d 0" ; all numeric newsgroups from both hosts will be processed. .TP .BI \-g " max" @@ -300,7 +302,7 @@ .in +0.5i .nf alt.feinstien.acts.like.a.republican -alt.exon.admendment +alt.exon.amendment alt.crypto.export.laws .fi .in -0.5i @@ -314,7 +316,9 @@ .TP .BI \-i " ignore_file" The -.I ignore_file +.I ignore_file , +usually +.I /actsync.ign , allows one to have a fine degree of control over which newsgroups are ignored. It contains a set of rules that specifies which newsgroups will be checked and which will be ignored. @@ -330,7 +334,7 @@ if specified, or if the ignore file contains no rule lines, all newsgroups will be checked. .sp 1 -Blank lines, and text after a +Blank lines and text after a .B ``#'' are considered comments and are ignored. .sp 1 @@ -361,9 +365,8 @@ are specified, then the rule applies to the newsgroup only if is of the specified type. Types refer to the 4th field of the -.IR active (5) -file. -A type may be one of: +.I active +file; that is, a type may be one of: .sp 1 .in +0.5i .nf @@ -378,7 +381,7 @@ .sp 1 Unlike active files, the .B group.name -may be a newsgroup name or a +in an alias type may be a newsgroup name or a .IR uwildmat (3) pattern. Also, @@ -386,13 +389,13 @@ is equivalent to .BR ``=*'' . .sp 1 -For given rule line may, one may not repeat a given pattern type. +On each rule line, no pattern type may not be repeated. For example, one may not have more than one type that begins with .BR ``='' , per line. -However, one may achieve the effect of multiple +However, one may achieve an effect equivalent to using multiple .B ``='' -types by using multiple rule lines for the same group. +types by using multiple rule lines affecting the same newsgroup. .sp 1 By default, all newsgroups are candidates to be checked. If an ignore file is used, each newsgroup in turn is checked @@ -410,22 +413,25 @@ .fi .in -0.5i .sp 1 -The newsgroup: +The newsgroups .B ba.general -would be ignored if it was not moderated. -The newsgroup: +and .B mod.general -would be checked if it was moderated. -The newsgroup: +would be synchronized if moderated and ignored if not moderated. +The newsgroup .B nsa.general -would be ignored even if it was moderated. +would be ignored regardless of moderation status. +All newsgroups not matching +.B *.general +would be synchronized by default. .TP .BI \-I " hostid" -This flag restricts which hosts, the ignore file applies. +This flag restricts which hosts are affected by the ignore file. The .B hostid value is interpreted the same as in -.BR \-b . +.BR \-b +described above. .sp 1 This flag may be useful in conjunction with the .B \-m @@ -433,18 +439,23 @@ For example: .sp 1 .in +0.5i -actsync \-i actsync.ign \-I 2 \-m host1 host2 +actsync \-i actsync.ign \-I 2 \-m +.I host1 +.I host2 .in -0.5i .sp 1 -will keep all newsgroups currently on host1. -It will also will only compare host1 groups with -non-ignored newsgroups from host2. +will keep all newsgroups currently on +.I host1 . +It will also will only compare +.I host1 +groups with non-ignored newsgroups from +.I host2 . .sp 1 The default is .BR "\-I 12" , -newsgroups from both hosts to be ignored per the -.I \-I " hostid" -flag. +newsgroups from both hosts to be ignored per the +.I \-i " actsync.ign" +file. .TP .B \-k By default, any newsgroup on @@ -453,18 +464,18 @@ This causes .IR actsync (8) simply ignore such newsgroups. -This flag, in combination with -.I \-m +This flag, used in combination with +.I \-m , will prevent any newsgroup from being scheduled for removal. .TP .BR \-l " hostid" -Flag problem newsgroups of type +This flag causes ``problem newsgroups'' of type .B ``='' from .B host1 or .B host2 -as errors. +to be considered as errors. The .B hostid value is interpreted the same as in @@ -473,17 +484,22 @@ .B ``='' are newsgroups active entries that have 4th field that begins with -.BR ``='' . -I.e., a newsgroup that is equivalent to another newsgroup. +.BR ``='' , +i.e. newsgroups that are equivalent to other newsgroups. A ``problem'' +newsgroup is one which is: .sp 1 -A newsgroup that is equivalent to itself, or that is in a equivalence -chain that loops around to itself is a problem. -A newsgroup that is in a chain that is longer than -.B 16 -is a problem group. -A newsgroup that is equivalent to a non-existent newsgroup is a problem. -A newsgroup that is equivalent to a newsgroup that is has a error -of some kind a problem. +.in +0.5i +.nf +* equivalent to itself +* in an equivalence chain that loops around + to itself +* in an equivalence chain longer than 16 groups +* equivalent to a non-existant newsgroup +* equivalent to a newsgroup that has an error + of some kind +.fi +.in -0.5i +.sp 1 However, a newsgroup that is equivalent to an ignored newsgroup is not a problem. .sp 1 @@ -502,9 +518,9 @@ to be kept. .TP .B \-n " name" -Newsgroups that are created, are created via the +The .IR ctlinnd (8) -command. +command is used to create newsgroups as necessary. By default, the creator name used is .BR "actsync" . This flag changes the creator name to @@ -518,29 +534,29 @@ .sp 1 .in +0.5i .nf -\fBa\fP output in \fIactive\fP\fR(5)\fP\fR format,\fP +\fBa\fP output in \fIactive\fP\fR(5)\fP\fR format\fP \fBa1\fP output in \fIactive\fP\fR(5)\fP\fR format,\fP - and output host1 non-error ignored groups + and output host1 non-error ignored groups \fBak\fP output in \fIactive\fP\fR(5)\fP\fR format, but use host2\fP - hi & low (2nd & 3rd active fields) values - for any newsgroup being created + hi & low (2nd & 3rd active fields) values + for any newsgroup being created \fBaK\fP output in \fIactive\fP\fR(5)\fP\fR format, but use host2\fP - hi & low (2nd & 3rd active fields) values - for all newsgroups found in host2 + hi & low (2nd & 3rd active fields) values + for all newsgroups found in host2 \fBa1k\fP output in \fIactive\fP\fR(5)\fP\fR format, but use host2\fP - hi & low (2nd & 3rd active fields) values - for any newsgroup being created, + hi & low (2nd & 3rd active fields) values + for any newsgroup being created, and output host1 non-error ignored groups \fBa1K\fP output in \fIactive\fP\fR(5)\fP\fR format, but use host2\fP - hi & low (2nd & 3rd active fields) values - for all newsgroups found in host2, + hi & low (2nd & 3rd active fields) values + for all newsgroups found in host2, and output host1 non-error ignored groups \fBak1\fP same as \fBa1k\fP \fBaK1\fP same as \fBa1K\fP \fBc\fP output in \fIctlinnd\fP\fR(8)\fP\fR format\fP \fBx\fP no output, directly exec \fIctlinnd\fP\fR(8)\fP\fR commands\fP \fBxi\fP no output, directly exec \fIctlinnd\fP\fR(8)\fP\fR commands,\fP - in an interactive mode + in an interactive mode .fi .in -0.5i .sp 1 @@ -570,7 +586,7 @@ simply prints .IR ctlinnd (8) commands on standard output. -The sync (or merge if \fI\-m\fP) with +The sync (or merge) with .B host2 may be accomplished by piping this output into .IR sh (1). @@ -580,22 +596,22 @@ .IR sh (1). Even so, this output format is useful to let you see how .B host1 -may be synced (or merge) with +will be affected by the sync (or merge) with .BR host2 . .sp 1 -The sync (or merge if \fI\-m\fP) may be accomplished directly -by use of the \fBx\fP. +The sync (or merge) may be accomplished directly +by use of the \fBx\fP format. With this format, .IR actsync (8) uses the .IR execl (2) -system call to directly executes +system call to directly execute .IR ctlinnd (8) commands. Because of the exec, there is no risk of bogus newsgroups containing bogus characters causing a shell to do bogus (or dangerous) things. -The output of such execs may be seen of the verbosity level +The output of such exec calls may be seen if the verbosity level is at least .BR 2 . .sp 1 @@ -608,7 +624,7 @@ is selected. See the .BR \-z " sec" -flag below. +flag below for discussion of this delay and how to customize it. .sp 1 The \fBxi\fP format interactively prompts on standard output and reads directives on standard input. @@ -620,9 +636,9 @@ .IR actsync (8) exited with a zero status prior to using such output. Also one should realize that such output will not -contain lines ignored by the +contain lines ignored due to .BI \-i " ignore_file" -process even if +even if .BI \-p " 100" is used. .sp 1 @@ -644,13 +660,12 @@ exits with a non-zero exit status. The .B min_%_unchg -may be a floating point value such as -.BR 66.666 . +may be a floating point value such as +.BR 66.667 . .sp 1 -A change is considered a +A change is considered a .B host1 -line that was found to be in error, -was removed, was added or was changed. +line that was removed, added, changed, or found to be in error. Changing the 2nd or 3rd active fields via .BI \-o "ak" or @@ -670,8 +685,8 @@ option. .sp 1 Care should be taken when producing -\fIactive\fP\fR(5)\fP\fR formatted output\fP. -One should check to be sure that +\fIactive\fP\fR(5)\fP\fR-formatted output\fP; +be sure to check that .IR actsync (8) exited with a zero status prior to using such output. Also one should realize that such output will not @@ -684,11 +699,11 @@ By default, 96% of the lines not ignored in host1 must be unchanged. That is, by default, -.BI \-p " 90" +.BI \-p " 96" is assumed. .TP .BI \-q " hostid" -By default, all newsgroup errors are reported on standard errors. +By default, all newsgroup errors are reported on standard error. This flag quiets errors from .B host1 or @@ -699,20 +714,22 @@ .BR \-b . .TP .BR \-s " size" -If -.BR size >0, +If +.BR size\ >\ 0, then ignore newsgroups with names longer than .BR size , -and ignore newsgroups equivalenced to names longer than +and ignore newsgroups equivalent (by following +.B ``='' +chains) to names longer than .BR size . -Length checking is perform on both the local and remote hosts. +Length checking is performed on both the local and remote hosts. .sp 1 By default, .B size is 0 and thus no length checking is performed. .TP .BR \-t " hostid" -Ignore improper newsgroups with only a top component +Ignore improper newsgroups consisting of only a top component from .B host1 or @@ -722,7 +739,7 @@ value is interpreted the same as in .BR \-b . The following newsgroups are considered proper newsgroups -for top only names: +despite top only names and therefore are exempt from this flag: .sp 1 .in +0.5i .nf @@ -742,34 +759,34 @@ dole_for_pres dos microsoft -windoes95 +windows95 .fi .in -0.5i .sp 1 -By default, all improper top level only newsgroups from the remote ( -.BI \-t " 2" -) are ignored. +The default is +.BR "\-t 2" , +that is, all improper top-level-only newsgroups from the remote +are ignored. .TP .B \-T -This flag causes -.B host2 -newsgroups from new hierarchies to be ignored. -Normally if only +This flag causes .B host2 -has the newsgroup -.B chongo.was.here -then it will be created for +newsgroups from new hierarchies to be ignored. +Normally a newsgroup which only exists on +.B host2 , +for example +.B chongo.was.here , +will be created for .BR host1 . -However if +However, if this flag is given and .B host1 -does not have any '\fBchongo.*\fP' newsgroups and this -flag is given, then -.B chongo.was.here +does not have any other newsgroups in the same hierarchy, +e.g. ``\fBchongo.*\fP'', then the newsgroup in question will be ignored and will not be created on .BR host1 . .TP -.BI \-v " verbose_lvl" -No default, +.BI \-v " verbosity" +By default, .IR actsync (8) is not verbose. This flag controls the verbosity level as follows: @@ -778,10 +795,10 @@ .nf \fB0\fP no debug or status reports (default) \fB1\fP print summary, - if work was needed or done -\fB2\fP print actions, exec output & summary, - if work was needed or done -\fB3\fP print actions, exec output & summary + but only if work was needed or done +\fB2\fP print actions, exec output, and summary, + but only if work was needed or done +\fB3\fP print actions, exec output, and summary \fB4\fP full debug output .fi .TP @@ -798,7 +815,7 @@ from being busied-out if a large number of .IR ctlinnd (8) commands are needed. -One can disable this sleeping by using +One can entirely disable this sleeping by using .BI \-z " 0". .sp 1 By default, @@ -920,7 +937,7 @@ host=news.uu.net # location of the ignore file -ignore_file=/etc/actsync.ign +ignore_file=/actsync.ign # where news articles are kept spool= @@ -930,7 +947,7 @@ # Automatic execs, report if something was done, # otherwise don't say anything, don't report # uunet active file problems, just ignore -# the effect entries. +# the affected entries. flags=\-o x \-v 2 \-q 2 .fi .in -0.5i @@ -938,19 +955,19 @@ and then by running .IR actsyncd (8) with the path to the config -file. +file: .PP .in +0.5i -actsyncd /etc/actsync.cfg +actsyncd /actsync.cfg .in -0.5i .PP -One may produce a trial +One may produce a trial .IR actsyncd (8) run without changing anything on the server by supplying the \fBdebug_level\fP arg: .sp 1 .in +0.5i -actsyncd /etc/actsync.cfg 2 +actsyncd /actsync.cfg 2 .in -0.5i .PP The \fBdebug_level\fP causes @@ -959,28 +976,31 @@ .IR actsync (8) with an \fB\-v debug_level\fP (overriding any \fB\-v\fP flag on the \fBflags\fP line), -prevents any changes from being made to the -.IR active (5) -file, writes a new active file to \fIstandard output\fP -and writes debug messages to \fIstandard error\fP. +not make any changes to the +.I active +file, write a new active file to \fIstandard output\fP, +and write debug messages to \fIstandard error\fP. .PP If the \fBdebug_outfmt\fP arg is also given to .IR actsyncd (8) -then the data written to \fIstandard output\fP will +then the data written to \fIstandard output\fP will be in \fB\-o debug_outfmt\fP instead of in \fB\-o a1\fP format. -The following /bin/sh command: +The /bin/sh command .sp 1 .in +0.5i -actsyncd /etc/actsync.cfg 4 >cmd 2>dbg +.nf +actsyncd /actsync.cfg 4 \\ + >cmd.log 2>dbg.log +.fi .in -0.5i .PP -Will operate in debug mode, +will operate in debug mode, not change the -.IR active (5) +.I active file, write .IR ctlinnd (8) -style commands to \fBcmd\fP and -write debug statements to \fBdbg\fP. +style commands to \fBcmd.log\fP, and +write debug statements to \fBdbg.log\fP. .PP To check only the major hierarchies against news.uu,net, use the following .B actsync.ign @@ -1004,7 +1024,7 @@ .fi .in -0.5i .PP -and running: +and the command: .PP .in +0.5i actsync \-i actsync.ign news.uu.net @@ -1035,13 +1055,13 @@ The active file produced by: .PP .in +0.5i -actsync ... flags ... \-o x erehwon.honey.edu +actsync ...flags... \-o x erehwon.honey.edu .in -0.5i .PP or by: .PP .in +0.5i -actsync ... flags ... \-o c erehwon.honey.edu | sh +actsync ...flags... \-o c erehwon.honey.edu | sh .in -0.5i .PP is effectively the same as the active file produced by: @@ -1050,7 +1070,7 @@ .in +0.5i ctlinnd pause 'running actsync' rm -f active.new -actsync ... flags ... \-o a1 erehwon.honey.edu > active.new +actsync ...flags... \-o a1 erehwon.honey.edu > active.new rm -f active.old ln active active.old mv active.new active @@ -1059,12 +1079,14 @@ .in -0.5i .fi .PP -It should be noted that the above 'pause', 'actsync', 'reload' and 'go' -method is faster. +It should be noted that the final method above, pausing the server +and simply replacing the +.I active +file, is faster. .PP .SH CAUTION -Careless use of this tool may result in the addition -change or removal of newsgroups that you don't want. +Careless use of this tool may result in the unintended +addition, change, or removal of newsgroups. You should avoid using the \fRx\fP output format until you are sure it will do what you want. .SH BUGS Index: doc/man/archive.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/archive.8,v retrieving revision 1.9 diff -u -r1.9 archive.8 --- doc/man/archive.8 2002/08/10 18:51:31 1.9 +++ doc/man/archive.8 2002/12/03 04:42:54 @@ -17,7 +17,7 @@ .BI \-i " index" ] [ -.BI \-p " newsgroups\ list" +.BI \-p " newsgroup-list" ] [ .B \-r @@ -38,10 +38,10 @@ reads the named .I input file, or standard input if no file is given. -The input is taken as a set of lines. -Blank lines and lines starting with a number sign (``#'') are ignored. +The input is taken as a sequence of lines; +blank lines and lines starting with a number sign (``#'') are ignored. All other lines should specify the token of an article to archive. -Every article is retrieved from a token +Every article is retrieved from a token, and the Xref: header is used to determine the target file in the archive directory. You can limit the targets taken from the Xref: header with the ``\-p'' option. @@ -51,24 +51,26 @@ The default is to create a hierarchy that mimics the input files; intermediate directories will be created as needed. For example, if the input token represents article 2211 in the newsgroup -comp.sources.unix, it will be copied to -.IR /comp/sources/unix/2211 .) +comp.sources.unix, +.IR archive +will generate a copy in +.IR /comp/sources/unix/2211 . .SH OPTIONS .TP -.B \-a archive +.B \-a\ archive If the ``\-a'' flag is used then its argument specifies the directory to -archive in instead of the default. +archive in instead of +.IR . .TP .B \-c -If the ``\-c'' flag is used, then all directory names will be flattened -out, replacing the slashes with periods; and all posts will be concatenated -into a single file with the final component name being YYYYMM which means -the local execution time of -.IR archive (8). +If the ``\-c'' flag is used, then directory names will be flattened as if +by the ``\-f'' flag; additionally, all posts will be concatenated into a +.B single\ file , +appending if the file already exists, with the final component of the +filename being YYYYMM based on the local execution time of +.IR archive. In this case, on December 14, 1998, the file would be copied to .IR /comp.sources.unix/199812 . -.B Note: -The ``\-c'' flag implies the ``\-f'' flag. .TP .B \-f If the ``\-f'' flag is used, then all directory names will be @@ -82,17 +84,19 @@ will append one line to the specified .I index file for each article that it copies. -This line will contain the destination name and the Message-ID and +This line will contain the destination name as well as the Message-ID and Subject headers. .TP -.B \-p -Limits the targets taken from the Xref: header to the groups specified in the -.I newsgroups\ list. +.B \-p newsgroup-list +Limits the targets taken from the Xref: header to the groups specified in +.I newsgroup-list. The -.I newsgroups\ list -is a comma separated +.I newsgroup-list +is a comma-separated .IR uwildmat (3) -list of newsgroups you wish to have archive handle. +list of newsgroups you wish to have +.IR archive +handle. .TP .B \-r By default, @@ -131,7 +135,7 @@ source-archive\e :!*,*sources*,!*wanted*,!*.d\e :Tc,Wn\e - :/archive \-f \-i \e + :/archive \-f \-i \e /INDEX .fi .RE Index: doc/man/batcher.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/batcher.8,v retrieving revision 1.6 diff -u -r1.6 batcher.8 --- doc/man/batcher.8 2000/08/17 13:30:06 1.6 +++ doc/man/batcher.8 2002/12/03 04:42:54 @@ -1,7 +1,7 @@ .\" $Revision: 1.6 $ .TH BATCHER 8 .SH NAME -batcher \- article batching backend for InterNetNews +batcher \- article-batching backend for InterNetNews .SH SYNOPSIS .B batcher [ @@ -60,24 +60,25 @@ Relative pathnames are interpreted from the .I directory. -The input is taken as a set of lines. -Blank lines and lines starting with a number sign (``#'') are ignored. +The input is taken as a sequence of lines; +blank lines and lines starting with a number sign (``#'') are ignored. All other lines should consist of one or two fields separated by a single space. The first field is the name of a file holding an article; if it is not an -an absolute pathname it is taken relative to the news spool directory, +an absolute pathname it is taken relative to .IR . The second field, if present, specifies the size of the article in bytes. .SH OPTIONS .TP -.B \-S +.B \-S alt_spool The ``\-S'' flag may be used to specify an alternate spool directory to -use if the article is not found; this would normally be an NFS-mounted +use if the article is not found; this would perhaps be an NFS-mounted spool directory of a master server with longer expiration times. .TP .B \-r -By default, the program sets its standard error to +By default, the program reports errors to .IR /errlog . -To suppress this redirection, use the ``\-r'' flag. +To suppress this redirection and report errors to standard error, +use the ``\-r'' flag. .TP .B \-v Upon exit, @@ -87,32 +88,32 @@ If the ``\-v'' flag is used, they will also be printed on the standard output. .TP -.B \-b +.B \-b size .I Batcher collects the text of the named articles into batches. To limit the size of each batch, use the ``\-b'' flag. The default size is 60 kilobytes. -Using ``\-b0'' allows unlimited batch sizes. +Using ``\-b\ 0'' allows unlimited batch sizes. .TP -.B \-a +.B \-a arts To limit the number of articles in each batch, use the ``\-a'' flag. The default is no limit. A new batch will be started when either the byte count or number of articles written exceeds the specified limits. .TP -.B \-B +.B \-B total_size To limit the total number of bytes written for all batches, use the ``\-B'' flag. .TP -.B \-A +.B \-A total_arts To limit the total number of articles that can be batched use the ``\-A'' flag. .TP -.B \-N +.B \-N num_batches To limit the total number of batches that should be created use the ``\-N'' flag. .IP -In all three cases, the default is zero, which is taken to mean no limit. +In all three of the above cases, the default is zero, that is, no limit. .TP .B \-i string A batch starts with an identifying line to specify the unpacking method @@ -122,7 +123,7 @@ followed by a newline, will be output at the start of every batch. The default is to have no initial string. .TP -.B \-s +.B \-s separator Each article starts with a separator line to indicate the size of the article. To specify the separator use the ``\-s'' flag. This is a @@ -131,9 +132,9 @@ the size of the article. If the separator is not empty, then the string and a newline will be output before every article. -The default separator is ``#! rnews %ld''. +The default separator is ``#!\ rnews\ %ld''. .TP -.B \-p +.B \-p process By default, batches are written to standard output, which is not useful when more than one output batch is created. Use the ``\-p'' flag to specify the shell command that should be @@ -141,7 +142,7 @@ .IR popen (3)) whenever a new batch is started. The process is a -.I sprintf +.IR sprintf (3) format string which can have a single ``%s'' parameter which will be given the host name. A common value is: @@ -156,21 +157,22 @@ If the input is exhausted, .I batcher will exit with a zero status. -If any of the limits specified with the ``\-B,'' ``\-A,'' or ``\-N'' flags +If any of the limits specified with the ``\-B'', ``\-A'', or ``\-N'' flags is reached, or if there is an error writing the batch, then .I batcher -will try to spool the input, copying it to a file. -If there was no input filename, the standard input will be copied to +will try to spool the remaining input, copying it to a file. +If there was no input filename, standard input will be copied to .I /host and the program will exit. -If an input filename was given, a temporary file named +If an input filename was given, the input will be copied to +a temporary file named .IR input .bch (if .I input is an absolute pathname) or .I /input.bch -(if the filename does not begin with a slash) is created. +(if the filename does not begin with a slash). Once the input is copied, .I batcher will try to rename this temporary file to be the name of the input file, Index: doc/man/buffchan.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/buffchan.8,v retrieving revision 1.7 diff -u -r1.7 buffchan.8 --- doc/man/buffchan.8 2000/08/17 13:30:06 1.7 +++ doc/man/buffchan.8 2002/12/03 04:42:55 @@ -17,7 +17,7 @@ .BI \-d " directory" ] [ -.BI \-f " fields" +.BI \-f " num_fields" ] [ .BI \-m " map" @@ -35,7 +35,7 @@ .B \-r ] [ -.BI \-s " file_format" +.BI \-s " filename_format" ] [ .B \-u @@ -54,36 +54,34 @@ Once .I buffchan opens a file it keeps it open. -The input must therefore never specify more files than can the +The input must therefore never specify more files than the number of available descriptors can keep open. If the ``\fB\-b\fP'' flag is used, the program will allocate a buffer and attach it to the file using .IR setbuf (3). .TP -.B \-c -If the ``\fB\-c\fP'' flag is used with a number -.IR n , -then +.B \-c lines +If the ``\fB\-c\fP'' flag is used, .I buffchan will close, and re-open, a file after every -.I n +.I lines lines are written to a file. .TP -.B \-C +.B \-C seconds Similarly, the ``\fB\-C\fP'' flag may be used to specify that all files should be closed and re-opened every -.I n +.I seconds seconds. .TP -.B \-d +.B \-d directory The ``\fB\-d\fP'' flag may be used to specify a directory the program should change to before starting. If this flag is used, then the default for the ``\fB\-s\fP'' flag is changed to -be a simple ``%s.'' +be a simple ``%s''. .TP -.B \-f +.B \-f num_fields Buffchan -input is interpreted as a set of lines. +input is interpreted as a sequence of lines. Each line contains a fixed number of initial fields, followed by a variable number of filename fields. All fields in a line are separated by whitespace. @@ -91,41 +89,37 @@ flag may be used to specify a different number of fields. .TP -.B \-m -See +.B \-m map +Map files specify short names as aliases for domain names; see .IR filechan (8) -for an example. +for details and an example. .TP -.B \-p +.B \-p pidfile If the ``\fB\-p\fP'' flag is used, the program will write a line containing its process ID (in text) to the specified file. .TP -.B \-l -If the ``\fB\-l\fP'' flag is used with a number -.IR n , -then +.B \-l lines +If the ``\fB\-l\fP'' flag is used, .I buffchan will call .IR fflush (3) after every -.I n +.I lines lines are written to a file. .TP -.B \-L -If the ``\fB\-L\fP'' flag is used with a number -.IR n , -then all files will be flushed every +.B \-L seconds +If the ``\fB\-L\fP'' flag is used, +all files will be flushed every .I n seconds. .TP .B \-r -By default, the program sets its standard error to +By default, the program sends its error messages to .IR /errlog . - - -To suppress this redirection, use the ``\fB\-r\fP'' flag. +To suppress this redirection and send error messages to standard error, +use the ``\fB\-r\fP'' flag. .TP -.B \-s +.B \-s filename_format After the initial fields, each remaining field names a file to write. The ``\fB\-s\fP'' flag may be used to specify a format string that maps @@ -133,7 +127,7 @@ This is a .IR sprintf (3) format string which should have a single ``%s'' parameter which will be given -the field. +the contents of a non-initial field. The default value is .IR /%s . See the description of this flag in @@ -170,8 +164,8 @@ the same file. .TP .B drop -The ``drop'' command is similar to the ``flush'' command except that any -files are not re-opened. +The ``drop'' command is similar to the ``flush'' command except that no +files are re-opened. If given an argument, then the specified site is dropped, otherwise all sites are dropped. (Note that the site will be restarted if the input stream mentions the @@ -182,7 +176,7 @@ .I innd will automatically forward the command to .I buffchan -if the site is a funnel that feeds into this exploder. +for sites listed as funnels feeding into this exploder. To drop all sites, use the .I ctlinnd \&``send buffchan-site drop'' command. Index: doc/man/buffindexed.conf.5 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/buffindexed.conf.5,v retrieving revision 1.6 diff -u -r1.6 buffindexed.conf.5 --- doc/man/buffindexed.conf.5 2000/10/12 10:07:15 1.6 +++ doc/man/buffindexed.conf.5 2002/12/03 04:42:55 @@ -8,22 +8,21 @@ is required if buffindexed ovmethod is used. .PP Buffindexed is one of ovmethod which is specified in -.IR inn.conf (5). -It uses preconfigured buffer files which are used to store overview data -and index, and never needs more disk space other than those files. -The files are devided 8KB block internally and the block is allocated -for each purpose; overview index and overview data. The block is never -shared by each newsgroup, so owned by one newsgroup. There is a database -file: +.IR inn.conf . +It uses preconfigured buffer files to store overview data and index, and +never needs more disk space other than those files. The files are divided +into 8 KB blocks internally; a given block is allocated for either overview +index or overview data. A block is never shared among multiple newsgroups. +There is a database file: .I /group.index -which includes the information of the newsgroup; the pointer to the index +that includes information about each newsgroup: the pointer to the index block for the group, high mark, low mark, flag of the group, the number of -the articles and etc. This file is created automatically when all buffers +articles, and etc. This file is created automatically when all buffers are initialized and must not be edited manually. If all buffers are filled up, .IR innd (8) throttles itself. Note that the buffer files are never rolled over and -overwritten the way CNFS does. You need to append another buffer file in the -case. You can see the buffer usage with +overwritten the way CNFS does. You need to append another buffer file in +this event. You can see the buffer usage with .IR inndf (8) with ``-o'' option. .PP @@ -41,39 +40,42 @@ \&``Index'' is an index of overview buffer. \&``Index'' must be between 0 and 65535. \&``File_name'' is the path to overview buffer file. -The length of this path should be within 63 letters. +The length of this path should be not more than 63 characters. \&``Buffer_size'' is the length of buffer file in kilobytes -in decimal (1KB = 1024 bytes). If the ``file_name'' is not a special -device, actucal file size must be buffer_size * 1024 bytes. -You can NOT use buffers over 2GB even if you specify -.IR <\-\-with\-largefiles\ at\ configure> . -Or buffers will be broken. It'll be fixed in the future. +in decimal (1 KB = 1024 bytes). If the ``file_name'' is not a special +device, the actual file size must be buffer_size * 1024 bytes. +You can NOT use buffers over 2 GB even if you specify +.IR <\-\-with\-largefiles\ at\ configure> , +or buffers will be broken. It'll be fixed in the future. .PP -To create new overview buffer, there are two different methods for creating -the files. +When creating new overview buffer, there are two different methods for +creating the files. .TP .BR 1. " Create a big file on top of a standard filesystem." -The use "dd" to create the overview buffer +.sp 1 +Use "dd" to create the overview buffer files, such as "dd if=/dev/zero of=/path/to/ovbuff bs=1024 count=N" where N is the buffer_size. .TP .BR 2. " Use block disk devices directly." +.sp 1 If your operating system will allow you to .I mmap() block disk devices (Solaris does, FreeBSD does not), this is the -recommended method. But note that Solaris(at least 2.6) seems to +recommended method. But note that Solaris (at least 2.6) seems to have a problem in regional locking of block disk devices, and should -not be used. Or overview data will be corrupted. -Partition the disks to make each partition -slightly larger (a few MB larger) than the intended size of each overview buffer. -It is not recommend to use the block device files already located in ``/dev.'' -Instead, use "mknod" to create a new set of block device files. +not be used as overview data will be corrupted. +.sp 1 +Partition the disks to make each partition slightly larger (a few MB larger) +than the intended size of each overview buffer. +It is not recommend to use the block device files already located in +``/dev''; instead, use "mknod" to create a new set of block device files. In order to do this, do an "ls -Ll" of the /dev/dsk partition. The major and minor device numbers are in the fifth and sixth columns (right -before the date) respectively. This information should be fed to "mknod" +before the date), respectively. This information should be fed to "mknod" to make a "block-type special file" (b). -Here is a short script that accomplishes this when fed the ``/dev/dsk/'' -partition name: +Here is a short script that accomplishes this when fed the name of the +partition as listed in ``/dev/dsk/'': .sp 1 .nf .in +0.5i @@ -85,6 +87,7 @@ mknod /ovbuff/$disk b $major $minor .in -0.5i .fi +.sp 1 The created device files themselves consume very little space. .PP In either case, make certain that each overview buffer file is owned by @@ -104,9 +107,9 @@ .in -0.5i .fi .PP -You MUST recreate whole overview, if you remove or relpace buffers. -You need not recreate, if you just append new buffers. And whenever -recreate overview data base, you need to clean all buffers. +You MUST entirely recreate overview if you remove or relpace buffers. +You need not recreate if you just append new buffers. And whenever you +recreate the overview data base, you need to clean all the buffers. .SH HISTORY Written by Katsuhiro Kondou for InterNetNews. .de R$ Index: doc/man/cnfsheadconf.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/cnfsheadconf.8,v retrieving revision 1.3 diff -u -r1.3 cnfsheadconf.8 --- doc/man/cnfsheadconf.8 2002/09/01 23:38:34 1.3 +++ doc/man/cnfsheadconf.8 2002/12/03 04:42:55 @@ -19,13 +19,13 @@ .I /cycbuff.conf and .I /storage.conf -to determine which cycbuff is available, reads the specified cycbuff and -modifies the header. +to determine which cycbuffs are available, reads the specified cycbuff, and +modifies the header as directed by the interactive user. .SH OPTIONS .TP .B \-c CLASS .I Cnfsheadconf -prints status for the specified class. +prints status of (and modifies, if appropriate) the specified class. .TP .B \-h .I Cnfsheadconf @@ -33,7 +33,7 @@ .TP .B \-w .I Cnfsheadconf -modifies cycbuff header. +prompts for modifications to make to cycbuff header. .SH HISTORY Written by Katsuhiro Kondou for InterNetNews. .de R$ Index: doc/man/cnfsstat.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/cnfsstat.8,v retrieving revision 1.6 diff -u -r1.6 cnfsstat.8 --- doc/man/cnfsstat.8 2002/09/01 23:38:35 1.6 +++ doc/man/cnfsstat.8 2002/12/03 04:42:55 @@ -37,8 +37,8 @@ .I /cycbuff.conf and .I /storage.conf -to read which cycbuff is available and read specified cycbuffs and -shows the usage of them. +to determine which cycbuffs are available, read the specified cycbuffs, and +shows their usage status. .PP .I Cnfsstat can be invoked from @@ -55,21 +55,23 @@ .TP .B \-c CLASS .I Cnfsstat -prints for the specified class. +prints information only for the specified class. .TP .B \-h .I Cnfsstat -prints the usage. +prints usage information. .TP .B \-l [ seconds ] .I Cnfsstat -never exits unless there is an error, and prints the snapshot every -.IR seconds . +prints a status snapshot every +.IR seconds , +and only exits if there is an error. The default interval is 600 seconds. .TP -.B \-m +.B \-m BUFFER .I Cnfsstat -prints out information suitable for mrtg. +prints information about the specified buffer in a format suitable +for mrtg. .TP .B \-P .I Cnfsstat @@ -78,12 +80,13 @@ .TP .B \-p .I Cnfsstat -prints out an mrtg config file. +prints an mrtg config file. .TP .B \-s .I Cnfsstat -prints the result to -.IR syslog (3). +writes output to +.IR syslog (3) +instead of standard output. .SH HISTORY Written by Katsuhiro Kondou for InterNetNews. .de R$ @@ -93,4 +96,5 @@ .SH "SEE ALSO" cycbuff.conf(5), inn.conf(5), +rc.news(8), storage.conf(5). Index: doc/man/controlchan.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/controlchan.8,v retrieving revision 1.4 diff -u -r1.4 controlchan.8 --- doc/man/controlchan.8 2001/05/14 04:18:44 1.4 +++ doc/man/controlchan.8 2002/12/03 04:42:56 @@ -13,21 +13,42 @@ To reduce load, .I controlchan keeps a copy of -.IR control.ctl (5) +.I control.ctl in memory and checks permissions (including any required PGP headers) before any scripts are called. Also, the default (``bad message'') case is handled internally. The ``drop'' case is handled with far less fuss. .PP Normally, .I controlchan -is configured in -.IR newsfeeds (5) -and invoked from -.IR innd (8). +is invoked by +.IR innd (8) +as configured in +.IR newsfeeds . +An example entry is below. Make sure that you've created the newsgroup +control.cancel so that +.I controlchan +doesn't have to scan through cancels, which it won't process anyway. +.sp 1 +.in +0.5i +.nf +controlchan!\\ + :!*,control,control.*,!control.cancel\\ + :Tc,Wnsm\\ + :/controlchan +.fi +.in -0.5i +.sp 1 +Note that in the (very, very unlikely) event that you need to process +ihave/sendme control messages, be sure that +.I logipaddr +is set to false in +.IR inn.conf , +because in this case controlchan needs a site name, not an IP address. +.sp 1 .I Controlchan -reports all log message through +tries to report all log messages through .IR syslog (3), -if possible. To enable +unless connected to an interactive terminal. To enable .IR syslog (3)'ing for versions of Perl prior to 5.6.0, you will need to have run ``h2ph'' on your Index: doc/man/ctlinnd.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/ctlinnd.8,v retrieving revision 1.23 diff -u -r1.23 ctlinnd.8 --- doc/man/ctlinnd.8 2002/03/25 02:14:37 1.23 +++ doc/man/ctlinnd.8 2002/12/03 04:42:57 @@ -33,9 +33,16 @@ If the server could not perform the command (for example, it was told to remove a newsgroup that does not exist), it will direct .I ctlinnd -to exit with a status of one. -The ``shutdown,'' ``xabort,'' and ``xexec'' commands do not generate a reply; +to exit with a status of one. (Note that .I ctlinnd +need not always exit immediately, see the ``\fB-t\fP'' flag.) +The ``shutdown'', ``xabort'', and ``xexec'' commands do not generate a +reply (because once +.I innd +has successfully exited, it is too late to send a reply to +.IR ctlinnd ); +after these commands, +.I ctlinnd will always exit silently with a status of zero. .SH OPTIONS .TP @@ -43,12 +50,14 @@ If the ``\fB\-s\fP'' flag is used, then no message will be printed if the command was successful. .TP -.B \-t +.B \-t timeout The ``\fB\-t\fP'' flag can be used to specify how long to wait for the reply -from the server. +from the server (for commands other than ``shutdown'', ``xabort'', and +``xexec''). The timeout value specifies the number of seconds to wait. A value of zero waits forever, and a value less -than zero indicates that no reply is needed. +than zero indicates that no reply is needed (that is, exit immediately +with status zero). When waiting for a reply, .I ctlinnd will try every two minutes to see if the server is still running, so it @@ -56,7 +65,7 @@ The default is set as .I (typically -.IR 0 .) +.IR 0 ). .TP .B \-h To see a command summary, use the ``\fB\-h\fP'' flag. @@ -70,7 +79,7 @@ If a parameter can be an empty string, then it is necessary to specify it as two adjacent quotes, like "". .TP -.BI addhist " arr exp post paths" +.BI addhist " arr exp post token" Add an entry to the history database. This directs the server to create a history line for .IR Message-ID . @@ -81,20 +90,15 @@ .I post specify when the article arrived, what its expiration date is, and when it was posted. -All three values are a number indicating the number of seconds since the +All three values are numbers indicating the number of seconds since the epoch. -If the article does not have an Expires header, then -.I exp -should be zero. -.I Paths -is the pathname within the news spool directory where the article is filed. -If the article is cross-posted, then the names should be separated by -whitespace and the -.I paths -argument should be inside double quotes. +.I Exp +being zero indicates the article does not have an Expires header. +.I Token +is the storage API token indicating where the article is stored. If the server is throttled manually, this command causes it to briefly open the history database. -And if the server is paused or throttled except that case, this command +If the server is paused or throttled for any other reason, this command is rejected. .TP .BI allow " reason" @@ -108,10 +112,10 @@ Begin feeding .IR site . This will cause the server to rescan the -.IR newsfeeds (5) +.I newsfeeds file to find the specified site and set up a newsfeed for it. If the site already exists, a ``drop'' is done first. -This command is forwarded; see below. +This command is forwarded; see NOTES below. .TP .BI cancel " " Remove the article with the specified Message-ID from the local system. @@ -121,7 +125,7 @@ The angle brackets are optional. If the server is throttled manually, this command causes it to briefly open the history database. -And if the server is paused or throttled except that case, this command +If the server is paused or throttled for any other reason, this command is rejected. .TP .BI changegroup " group rest" @@ -146,7 +150,7 @@ Flush and drop .I site from the server's list of active feeds. -This command is forwarded; see below. +This command is forwarded; see NOTES below. .TP .BI feedinfo " site" Print detailed information about the state of the @@ -160,13 +164,13 @@ Flush the buffer for the specified site. The actions taken depend on the type of feed the site receives; see .IR newsfeeds (5). -This is useful when the site is fed by a file and batching is going to start. +This is useful when the site is fed by a file and batching is about to start. If .I site is an empty string, then all sites are flushed and the .I active file and history databases are also written out. -This command is forwarded; see below. +This command is forwarded; see NOTES below. .TP .B flushlogs Close the log and error log files and rename them to have a @@ -217,7 +221,7 @@ .IR site , which must be a channel or exploder feed. .I Signal -can be a numeric signal number or the word ``hup,'' ``int,'' or ``term''; +can be a numeric signal number or the word ``hup'', ``int'', or ``term''; case is not significant. .TP .BI lowmark " file" @@ -250,8 +254,8 @@ .TP .BI name " nnn" Print the name and relevant information of channel number -.I nnn -or of all channels if it is an empty string. Format is: +.IR nnn , +or of all channels if it is an empty string. The response is formatted as: .sp 1 .in +0.5i .nf @@ -259,20 +263,20 @@ .fi .in -0.5i .sp 1 -And meaning of each field is: +Where the meanings of the fields are: .sp 1 .in +0.5i .nf f1 name of this channel f2 channel number f3 channel type -f4 idle time for this channel(nntp type) - or process id(process type) -f5 channel status(nntp type) +f4 idle time for this channel (nntp type) + or process id (process type) +f5 channel status (nntp type) .fi .in -0.5i .sp 1 -F3 is one of followings: +The channel type (f3) is one of following: .sp 1 .in +0.5i .nf @@ -291,12 +295,11 @@ .fi .in -0.5i .sp 1 -Channel status shows if the channel is paused or not. Nothing is -shown unless the channel is paused. Or ``paused'' is shown. -\&``Paused'' status happens, if the number of remote connection -for that label in -.IR incoming.conf (5) -is beyond ``max-connections'' within ``hold-time'' seconds since connected. +Channel status indicates whether the channel is paused or not. Nothing is +shown unless the channel is paused, in which case ``paused'' is shown. +A channel is paused if the number of remote connection for that label in +.I incoming.conf +is beyond ``max-connections'' within ``hold-time'' seconds of connection. .TP .BI newgroup " group rest creator" Create the specified newsgroup. @@ -307,7 +310,8 @@ if it is not an equal sign, only the first letter is used. The .I creator -should be the name of the person creating the group. +should be the identity of the person creating the group as described in +.IR active (5). If the newsgroup already exists, this is equivalent to the ``changegroup'' command. This is the only command that has defaults. @@ -317,15 +321,14 @@ time, ``usenet'' by default), and the .I rest parameter can be omitted and will default to ``y''. -This command can be done while the server is only throttled manually +This command can only be done while the server is throttled manually or running; it will update its internal state when a ``go'' command is sent. This command updates the .I active.times -(see -.IR active (5)) -file. -This command is forwarded; see below. +file (see +.IR active.times (5)). +This command is forwarded; see NOTES below. .TP .BI param " letter value" Change the command-line parameters of the server. @@ -341,7 +344,7 @@ connections. To enable or disable the action of the ``\fB\-n\fP'' flag, use the letter ``y'' or ``n'', respectively, for the -.IR value. +.IR value . .TP .BI pause " reason" Pause the server so that no incoming articles are accepted. @@ -368,7 +371,6 @@ .I flag starts with the letter ``y'' then filtering is enabled. If it starts with ``n'', then filtering is disabled. - .TP .BI readers " flag text" Allow or disallow newsreaders. @@ -404,18 +406,32 @@ The server updates its in-memory copies of various configuration files. .I What identifies what should be reloaded. -If it is an empty string or the word ``all'' then everything is reloaded; +The +.I reason +is reported to +.IR syslog . +.sp 1 +There is no way to reload the +.I inn.conf +file; use +.I "ctlinnd xexec innd" +instead. +.sp 1 +If +.I what +is an empty string or the word ``all'' then everything is reloaded; if it is the word ``history'' then the history database is closed and opened, if it is the word ``incoming.conf'' then the -.IR incoming.conf (5) +.I incoming.conf file is reloaded; if it is the word ``active'' or ``newsfeeds'' then both the .I active and .I newsfeeds files are reloaded; if it is the word ``overview.fmt'' then the -.IR overview.fmt (5) +.I overview.fmt file is reloaded. +.sp 1 If .I <\-\-with\-perl is specified at configure> and it is the word ``filter.perl'' then the @@ -432,6 +448,7 @@ to do this. The .I startup_innd.pl file cannot be reloaded. +.sp 1 If .I <\-\-with\-python is specified at configure> and it is the word ``filter.python'' then the @@ -463,13 +480,6 @@ The .I startup.tcl file cannot be reloaded. -The -.I reason -is reported to -.IR syslog . -There is no way to reload the data -.IR inn.conf (5) -file. .TP .BI renumber " group" Scan overview database for the specified newsgroup and update the @@ -479,10 +489,10 @@ If .I group is an empty string then all newsgroups are scanned. -Renumber never works, unless overview data is created. -See the description of ``enableoverview'' in +Renumber only works if overview data has been created. +(See the description of ``enableoverview'' in .IR inn.conf (5) -for overview creation. +for details about overview creation.) .TP .BI renumberlow " file" This command does same as ``lowmark'' command. @@ -503,12 +513,12 @@ .I active file. The spool directory is not touched, and any articles in the group will -be expired using the default expiration parameters. +still be expired using the default expiration parameters. Unlike the ``newgroup'' command, this command does not update the .I active.times file. This command can be done while the server is only throttled manually or running. -This command is forwarded; see below. +This command is forwarded; see NOTES below. .TP .BI send " feed text..." The specified @@ -519,28 +529,25 @@ .BI shutdown " reason" The server is shut down, with the specified reason recorded in the log and sent to all open connections. - +.sp 1 It is a good idea to send a ``throttle'' command first. - -If -.I <\-\-with\-python is specified at configure> -and a Python method named ``filter_close'' exists, -it will be called just before innd exits. -.TP -.BI stathist " flag" -Enable or disable getting statistics of history performance. It disables if -.I flag -is ``off''. Otherwise -.I flag -is treated as a filename to be written. The file can be parsed by -I contrib/stathist.pl . +.sp 1 +If Perl, Python, or TCL filtering is compiled in and enabled, certain +functions are called at ``throttle'' or ``shutdown'' (for example, to +save filter state to disk), consult the embedded filter documentation +for details. +.TP +.BI stathist " off|filename" +Enable or disable generation of history performance statistics. If the +parameter is ``off'', no statistics are gathered. Otherwise statistics +are written to the specified file. The file can be parsed by +.IR contrib/stathist.pl . .TP .BI status " off|interval" +Adjust frequency in seconds at which .I innd -status reporting is turned off if ``off'' or ``0'' is specified, -otherwise, status will be reported every -.I interval -seconds to syslog. See ``status'' in +reports status informatoin to syslog. Status reporting is turned off if +``off'' or ``0'' is specified. See ``status'' in .IR inn.conf (5) for information on how to set the startup default. .TP @@ -551,7 +558,6 @@ .I flag starts with the letter ``y'' then filtering is enabled. If it starts with ``n'', then filtering is disabled. - .TP .BI throttle " reason" Input is throttled so that all existing connections are closed and new @@ -580,7 +586,7 @@ should start with the letter ``y'' or ``n'' to turn tracing on or off. If .I item -starts is a number, then tracing is set for the specified +starts with a number, then tracing is set for the specified .I innd channel, which must be for an incoming NNTP feed. If it starts with the letter ``i'' then general @@ -589,9 +595,9 @@ If it starts with the letter ``n'' then future .IR nnrpd 's will or will not have the ``\-t'' flag enabled, as appropriate. -\&``n'' does not affect to -.I nnrpd -with ``-D'' (running as a daemon). +The ``n'' flag does not affect +.IR nnrpd 's +already running or using ``-D'' (running as a daemon). .TP .BI xabort " reason" The server logs the specified @@ -602,17 +608,18 @@ .TP .BI xexec " path" The server gets ready to shut itself down, but instead of exiting it -execs -.I /inndstart +.IR exec 's +.I /inndstart with all of its original arguments except for ``\fB\-r\fP''. .I Path -can be any of ``innd'', ``inndstart'' or an empty string. -any other value is an error. -.PP +can be any of ``innd'', ``inndstart'', or an empty string, although all +three valid parameters have exactly the same effect. +Any other value is an error. +.SH NOTES In addition to being acted upon within the server, certain commands can be forwarded to the appropriate child process. If the site receiving the command is an exploder (such as -.IR buffchan (8)) +.IR buffchan (8)), or it is a funnel that feeds into an exploder, then the command can be forwarded. In this case, the server will send a command line to the exploder that @@ -621,7 +628,7 @@ command name. If the site funnels into an exploder that has an asterisk (``*'') in its ``W'' flag (see -.IR newsfeed (5)), +.IR newsfeeds (5)), then the site name will be appended to the command; otherwise no argument is appended. .SH BUGS @@ -637,6 +644,7 @@ .R$ $Id: ctlinnd.8,v 1.23 2002/03/25 02:14:37 rra Exp $ .SH "SEE ALSO" active(5), +active.times(5), expire(8), innd(8), inndcomm(3), Index: doc/man/cvtbatch.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/cvtbatch.8,v retrieving revision 1.5 diff -u -r1.5 cvtbatch.8 --- doc/man/cvtbatch.8 1998/04/09 15:16:04 1.5 +++ doc/man/cvtbatch.8 2002/12/03 04:42:57 @@ -9,18 +9,21 @@ ] .SH DESCRIPTION .I Cvtbatch -reads standard input as a series of lines, converts each line, and +reads standard input as a sequence of lines, converts each line, and writes it to standard output. It is used to convert simple batchfiles that contain just the article name to INN batchfiles that contain additional information about each article. .PP -Each line is taken as the pathname to a Usenet article. -If it is not an absolute pathname, it is taken relative to the spool -directory, -.IR . +Each line is taken as a storage API token indicating a Usenet article. (Only the first word of each line is parsed; anything following -whitespace is ignored.) +whitespace is ignored. Lines not starting with a valid token are also +silently ignored.) +.PP +If the input file consists of a series of Message-ID's, then use +.IR grephistory (1) +with the `\fB`\-s\fP'' flag piped into +.IR cvtbatch . .SH OPTIONS .TP .B \-w @@ -29,6 +32,7 @@ specified in .IR newsfeeds (5). They may be chosen from the following set: +.PP .RS .nf b Size of article in bytes @@ -37,11 +41,6 @@ n relative pathname of article .fi .RE -.PP -If the input file consists of a series of Message-ID's, then use -.IR grephistory (1) -with the `\fB`\-s\fP'' flag piped into -.IR cvtbatch . .SH HISTORY Written by Rich $alz for InterNetNews. .de R$ Index: doc/man/cycbuff.conf.5 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/cycbuff.conf.5,v retrieving revision 1.14 diff -u -r1.14 cycbuff.conf.5 --- doc/man/cycbuff.conf.5 2000/08/17 13:30:08 1.14 +++ doc/man/cycbuff.conf.5 2002/12/03 04:42:57 @@ -6,18 +6,18 @@ The file .I /cycbuff.conf is required if CNFS (Cyclic News File System) method is used. -CNFS is one of storage method which can be defined at -.IR storage.conf (5). +CNFS is one of storage methods which can be used in +.IR storage.conf . .PP The file consists of a series of lines; blank lines and lines beginning with a number sign (``#'') are ignored. -There are four kinds of configuration lines: ``cycbuffupdate'', -``refreshinterval'', ``cycbuff'' and ``metacycbuff.'' +There are four kinds of configuration lines: \%``cycbuffupdate'', +\%``refreshinterval'', \%``cycbuff'' and \%``metacycbuff.'' The order of lines in this file is not important among the same kind of -configuration line. But all ``cycbuff'' lines should be presented before -any ``metacycbuff'' lines. +configuration line. But all \%``cycbuff'' lines should be presented before +any \%``metacycbuff'' lines. .PP -\&``Cycbuffupdate'' line is formatted as: +A \&``cycbuffupdate'' line is formatted as: .PP .RS .nf @@ -28,7 +28,7 @@ \&``Update'' is how many article-stores between cycbuff header updates. This line can be omitted and the default value is ``25.'' .PP -\&``Refreshinterval'' line is formatted as: +A \&``refreshinterval'' line is formatted as: .PP .RS .nf @@ -36,13 +36,13 @@ .fi .RE .PP -\&``Inerval'' is what interval (seconds) between rereading cycbuff header if -cycbuff is preopend. (This is in the case +\&``Interval'' is the interval (in seconds) between rereading cycbuff header if +cycbuff is preopened. (This is relevant when .IR nnrpd (8) -runs as a daemon.) -This line can be omitted and the default value is ``30.'' +is running as a daemon.) +This line can be omitted, and the default value is ``30.'' .PP -\&``Cycbuff'' line is formatted as: +A \&``cycbuff'' line is formatted as: .PP .RS .nf @@ -51,15 +51,15 @@ .RE .PP \&``Buffer_name'' is the symbolic name of the buffer. -The length of this name should be within 7 letters. -This name is referred at ``metacycbuff'' lines. +The length of this name should be not more than 7 letters. +This name is referred to from the ``metacycbuff'' lines. \&``File_name'' is the path to buffer file. -The length of this path should be within 63 letters. +The length of this path should be not more than 63 letters. \&``Buffer_size'' is the length of buffer file in kilobytes -in decimal (1KB = 1024 bytes). If the ``file_name'' is not a special -device, the file should be buffer_size * 1024 bytes. +in decimal (1 KB = 1024 bytes). If the ``file_name'' is not a special +device, the file should be buffer_size * 1024 bytes long. .PP -\&``Metacycbuff'' line is formatted as: +A \&``metacycbuff'' line is formatted as: .PP .RS .nf @@ -68,43 +68,51 @@ .RE .PP \&``Meta_cyclic_buffer_name'' is the symbolic name of meta-cyclic buffer. -This name is referred at ``options'' field at ``cnfs'' entries in -.IR storage.conf (5). -\&``Buffer_names'' is comma separated list of symbolic names of ``cycbuff.'' -These buffer names should be defined at ``cycbuff'' lines. -If ``buffer_names'' has more than one buffer names, CNFS method -stores articles into each ``cycbuff'' in order cyclically. -\&``Mode'' is the mode of storing article. Currently there are two mode; -\&``INTERLEAVE'' and ``SEQUENTIAL''. Mode ``INTERLEAVE'' is to store -articles into each cycbuff in round robin way. Mode ``SEQUENTIAL'' is to store -articles sequentially into one cycbuff until it is filled up. ``Mode'' is -optional and the default value without this option is ``INTERLEAVE''. -.PP -Also it is necessary to set up ``options'' field at ``cnfs'' entries in -.IR storage.conf (5) -to use CNFS method. -That field should be one of ``meta_cyclic_buffer_name'' defined at +This name is referred to in the ``options'' field of ``cnfs'' entries in +.IR storage.conf . +\&``Buffer_names'' is comma separated list of symbolic names indicating +which cycbuffs comprise this metacycbuff. +These buffer names should be defined earlier by ``cycbuff'' lines. +If ``buffer_names'' has multiple buffer names, the CNFS storage method +has two modes for distributing articles between the buffers. +\&``Mode'' is the mode for storing articles in this metacycbuff. Currently +there are two modes; \&``INTERLEAVE'' and ``SEQUENTIAL''. Mode +``INTERLEAVE'' is to store articles into each cycbuff in a round-robin way, +one article per cycbuff, in order. Note that this is unlikely to be what +you want if the cycbuffs are of widely different sizes, since some cycbuffs +will then cycle faster than others. Mode ``SEQUENTIAL'' is to store +articles sequentially into one cycbuff until it is filled up, and then move +on to the next. ``Mode'' is optional and the default value is +``INTERLEAVE''. +.PP +Also it is necessary to configure the ``options'' field of all ``cnfs'' +entries in +.I storage.conf +to be able to use the CNFS storage method. +That field should be a ``meta_cyclic_buffer_name'' as defined by \&``metacycbuff'' lines. .PP -To create new ``cycbuff'', there are two different methods for creating -the cyclic buffer files. +When creating a new ``cycbuff'', there are two different methods for +creating the cyclic buffer files. .TP .BR 1. " Create a big file on top of a standard filesystem." +.sp 1 The use "dd" to create the ``cycbuff'' files, such as "dd if=/dev/zero of=/path/to/cycbuff bs=32k count=N" where N is the buffer_size divided by 32. .TP .BR 2. " Use block disk devices directly." +.sp 1 If your operating system will allow you to .I mmap() block disk devices (Solaris does, FreeBSD does not), this is the recommended method. Partition the disks to make each partition -slightly larger (a few MB larger) than the intended size of each cycbuff. +slightly larger (by a few MB) than the intended size of each cycbuff. It is not recommend to use the block device files already located in ``/dev.'' Instead, use "mknod" to create a new set of block device files. In order to do this, do an "ls -Ll" of the /dev/dsk partition. The major and minor device numbers are in the fifth and sixth columns (right -before the date) respectively. This information should be fed to "mknod" +before the date), respectively. This information should be fed to "mknod" to make a "block-type special file" (b). Here is a short script that accomplishes this when fed the ``/dev/dsk/'' partition name: @@ -119,10 +127,11 @@ mkdir /cycbuff mknod /cycbuff/$disk b $major $minor .in -0.5i +.sp 1 .fi The created device files themselves consume very little space. .PP -In either case, make certain that each overview buffer file is owned by +In either case, make certain that each cycbuff file is owned by .IR , .IR , and has read/write modes for the owner and group (mode ``0664'' or ``0660''). Index: doc/man/distrib.pats.5 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/distrib.pats.5,v retrieving revision 1.7 diff -u -r1.7 distrib.pats.5 --- doc/man/distrib.pats.5 2002/08/10 18:51:31 1.7 +++ doc/man/distrib.pats.5 2002/12/03 04:42:57 @@ -9,16 +9,17 @@ It consists of a series of lines; blank lines and lines beginning with a number sign (``#'') are ignored. All other lines consist of three fields separated by a colon: +.sp 1 .RS .nf weight:pattern:value .fi .RE .PP -The first field is the weight to assign to this match. -If a newsgroup matches multiple lines, the line with the highest weight +The first field is the weight to assign to this match; +if a newsgroup matches multiple lines, the line with the highest weight is used. -This should be an arbitrary number greater than zero. +This should be an arbitrary integer greater than zero. Unlike other INN files, the order of lines in this file is not important. .PP The second field is the name of the newsgroup or a @@ -26,9 +27,9 @@ pattern to specify a set of newsgroups. Multiple patterns are not allowed. .PP -The third field is the value that should be used if this line is picked -as the best match. -It can be an empty string. +The third field is the value that should be used for the Distribution header +if this line is picked as the best match AND no Distribution header was +supplied by the user. It can be an empty string. .PP Programs such as .IR inews (1) Index: doc/man/expire.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/expire.8,v retrieving revision 1.21 diff -u -r1.21 expire.8 --- doc/man/expire.8 2001/07/25 11:59:10 1.21 +++ doc/man/expire.8 2002/12/03 04:42:58 @@ -55,35 +55,38 @@ .SH DESCRIPTION .I Expire scans the -.IR history (5) +.IR history (5)-format text file .I /history -and uses the information recorded in it to purge itself or old news articles. -And if the article whose storage method -has self expire functionality, the -control file is ignored except ``/remember/'' line for that article by default. -In this case, -.I expire -probes the article to see if it still exists. -If it does not exist, -.I expire -purges the relevant entries. -To disable this, use the ``\fB\-N\fP'' flag. -If ``groupbaseexpiry'' in +and uses the information recorded in it to purge itself of old news articles. +Articles stored using a storage method that has self-expire +functionality are by default not affected by +.IR expire 's +primary behavior (but see the ``\fB\-N\fP'' flag to disable this). In +this case, +.I expire.ctl +is ignored except ``/remember/'' line for that article; +.I expire +does still probe to see if the article still exists and purges the +relevant history and overview entries if appropriate. +However, if ``groupbaseexpiry'' in .I inn.conf is true, .I expire -always treats all stored articles whose storage method have self expire -functionality regardless of its actual method. In this case ``\fB\-e\fP'', -\&``\fB\-k\fP'', ``\fB\-N\fP'', ``\fB\-p\fP'', ``\fB\-q\fP'', ``\fB\-w\fP'' -and ``\fB\-z\fP'' flags are ignored. +acts on all articles as specified by +.I expire.ctl +regardless of whether their storage methods have self-expire +functionality. In this case, the ``\fB\-e\fP'', \&``\fB\-k\fP'', +``\fB\-N\fP'', ``\fB\-p\fP'', ``\fB\-q\fP'', ``\fB\-w\fP'' and +``\fB\-z\fP'' flags are ignored. .PP Note that .I expire -never purges articles which do not match any entry. +never purges articles which do not match any entry in +.IR expire.ctl . .SH OPTIONS .TP -.B \-d +.B \-d dir If the ``\fB\-d\fP'' flag is used, then the new history file and database is created in the specified directory, .IR dir . @@ -97,26 +100,26 @@ The calling script should install the new history file and un-pause the server. The ``\fB\-r\fP'' flag should be used with this flag. .TP -.B \-f +.B \-f file To specify an alternate history file, use the ``\fB\-f\fP'' flag. -This flag is valid if ``\fB\-d\fP'' flag is used together, and the output will -be written to this file. -The default without ``\fB\-f\fP'' flag is ``history.'' +This flag is valid when used with the ``\fB\-d\fP'', and the output will +be written to the specified file. +The default without ``\fB\-f\fP'' flag is ``history''. .TP -.B \-g +.B \-g file If the ``\fB\-g\fP'' flag is given, then a one-line summary equivalent to the -output of ``\fB\-v\fP 1'' and preceded by the current time, will be appended to -the specified +output of ``\fB\-v\fP 1'', except preceded by the current time, will be +appended to the specified .IR file . .TP -.B \-h +.B \-h file To specify an alternate input text history file, use the ``\fB\-h\fP'' flag. .I Expire uses the old .IR dbz (3) database to determine the size of the new one. -If ``\fB\-d\fP'' flag is not used together, and the output file name will be -with an extension of ``.n.'' +(If ``\fB\-d\fP'' flag is not used, the output filename will be the same +as the input filename with an extension of ``.n''.) The default without ``\fB\-h\fP'' flag is .IR /history . .TP @@ -124,12 +127,11 @@ To ignore the old database, use the ``\fB\-i\fP'' flag. .TP .B \-N -If the article whose storage method -has self expire functionality, then the control file is ignored for that -article by default. +The control file is normally ignored for articles in storage methods +which have self-expire functionality. If the ``\fB\-N\fP'' flag is used, .I expire -still uses the control file in this case. +still uses the control file for these articles. .TP .B \-n If @@ -155,7 +157,7 @@ date. To use the article's posting date, use the ``\fB\-p\fP'' flag. .TP -.B \-r +.B \-r reason .I Expire normally sends a ``pause'' command to the local .IR innd (8) @@ -166,13 +168,16 @@ When .I expire is finished and the new history file is ready, it sends a ``go'' command. +See also the ``\fB\-n\fP'' flag. .TP -.B \-s -Size the history database for approximately +.B \-s size +Optimize the new history database for approximately .I size -pairs. Accurately specifying the size is an optimization that will -create a more efficient database. (The size should be the estimated -eventual size of the file, typically the size of the old file.) +pairs (lines in +.IR history ). +Accurately specifying the size will create a more efficient database. +(The size should be the estimated eventual size of the file, typically +the size of the old file.) .TP .B \-t If the ``\fB\-t\fP'' flag is used, then @@ -189,23 +194,23 @@ name specified with that flag will be used instead of .IR history . .TP -.B \-v +.B \-v level The ``\fB\-v\fP'' flag is used to increase the verbosity of the program, generating messages to standard output. The .I level should be a number, where higher numbers result in more output. Level one will print totals of the various actions done (not valid if a -new history file is not written), level two will print report on each -individual file, while level five results in more than one line of output -for every line processed. +new history file is not written), level two will print a report on each +individual file, while level five results in multiple lines of output +for every history line processed. .TP -.B \-w +.B \-w number Use the ``\fB\-w\fP'' flag to ``warp'' time so that .I expire thinks it is running at some time other then the current time. -The value should be a signed floating point number of the number of days -to use as the offset. +The value should be a signed floating point number indicating the number +of days to use as the offset. .TP .B \-x If the ``\fB\-x\fP'' flag is used, then @@ -214,7 +219,7 @@ with the ``\fB\-n\fP'' and `\fB`\-t\fP'' flags to see how different expiration policies would change the amount of disk space used. .TP -.B \-z +.B \-z file If the ``\fB\-z\fP'' flag is used, then articles are not removed, but their names are appended to the specified .IR file . @@ -225,7 +230,7 @@ .PP If a filename is specified, it is taken as the control file and parsed according to the rules in -.IR expire.ctl (5). +.IR expire.ctl . A single dash (``\-'') may be used to read the file from standard input. If no file is specified, the file .I /expire.ctl Index: doc/man/expire.ctl.5 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/expire.ctl.5,v retrieving revision 1.17 diff -u -r1.17 expire.ctl.5 --- doc/man/expire.ctl.5 2002/08/10 18:51:31 1.17 +++ doc/man/expire.ctl.5 2002/12/03 04:42:58 @@ -10,12 +10,12 @@ or .IR expireover (8) program, which read it at start-up. -It serves two purposes: it defines how long history entries for expired or +It serves two purposes: it defines how long history entries for expired or rejected articles are retained, and it determines how long articles not stored in a self-expiring storage method are retained. If all of the storage methods used by the server are self-expiring (such -as CNFS), only the ``/remember/'' setting described below is necessary or -used. +as CNFS), all lines except the ``/remember/'' setting (described below) are +ignored. .PP Blank lines and lines beginning with a number sign (``#'') are ignored. All other lines should be in one of two formats. @@ -24,11 +24,13 @@ that aren't present in the news spool. These are articles which have either already expired out of spool or which the server rejected (and ``remembertrash'' was set to true in -.IR inn.conf (5)). +.IR inn.conf ). There should only be one line in this format, which looks like: +.sp 1 .RS /remember/:days .RE +.sp 1 where .I days is a floating-point number that specifies the minimum number of days a @@ -38,20 +40,21 @@ expires.) .PP The reason to retain a record of an old articles is to handle the case -where a peer offers old articles that were previously accepted and then +where a peer offers old articles that were previously accepted but then expired. Without a setting like this, the server would accept the article again and readers would see duplicate articles. Articles older than a certain number of days won't be accepted by the server at all (see the ``\fB-c\fP'' flag of .IR innd (8)), -and this setting should probably match that time period (14 days by +and this setting should probably match that time period (10 days by default) to ensure the server never accepts duplicates. .PP This setting does not affect article expirations. .PP -Most of the lines in this file will be in the second format, either four -or five colon-separated fields as follows: +Most of the lines in this file will be in the second format, which has two +variations consisting of four or five colon-separated fields as follows: +.sp 1 .RS .nf classnum:keep:default:purge @@ -63,22 +66,24 @@ pattern:modflag:keep:default:purge .fi .RE -The former is used for class based expiry which means ``groupbaseexpiry'' in -.IR inn.conf (5) -is ``false'', and the latter is used for group based expiry which +.sp 1 +The former is used for class-based expiry, which means ``groupbaseexpiry'' in +.I inn.conf +is ``false''; the latter is used for group-based expiry, which means ``groupbaseexpiry'' in .I inn.conf is ``true''. -Both formats can not coexist each other. +All lines must be in the format specified by ``groupbaseexpiry'' and +therefore the two formats can never coexist. .PP -Where +The .IR classnum -field used for class based expiry is the number that you specified in -.IR storage.conf (5). +field, used for class-based expiry, is the number that you specified in +.I storage.conf . .PP The .I pattern -field used for group based expiry is a list of +field used for group-based expiry is a list of .IR uwildmat (3)-style patterns, separated by commas. This field specifies the newsgroups to which the line is applied. @@ -89,8 +94,9 @@ .PP The .I modflag -field used for group based expiry can be used to further limit newsgroups to +field used for group-based expiry can be used to further limit newsgroups to which the line applies, and should be chosen from the following set: +.sp 1 .RS .nf M Only moderated groups @@ -99,15 +105,16 @@ X Removes the article from all groups that it appears in .fi .RE +.sp 1 (The X flag is special; normally articles are not completely deleted until they expire out of every group they were posted to, but if an article is expired by a line with an X, it is deleted out of all newsgroups it was posted to immediately.) .PP -The rest of three fields are used to determine how long an article +The remaining three fields are used to determine how long an article should be kept. Each field should be either a number of days (fractions like ``8.5'' are -allowed) or the word ``never.'' +allowed) or the word ``never''. The most common use is to specify the default value for how long an article should be kept. The first and third fields \(em @@ -118,9 +125,9 @@ header will be honored. They are ignored if an article has no Expires header. (In other words, if an article does not have an Expires header, -only +only the .I default -field is used and the Date header is be honored to expire. +field is used and the Date header will be honored to expire. But if an article has an Expires header, .I default is not used, and articles are expired no faster than the time set with @@ -137,11 +144,11 @@ .I keep field specifies how many days an article should be kept before it will be removed. -No article in the matching newsgroups or class will be removed if it has been -received for less than +No article in the matching newsgroups or class will be removed until it +has been present for at least .I keep days, regardless of Expires header. -If this field is the word ``never,'' no article in the matching newsgroups +If this field is the word ``never'', no article in the matching newsgroups or class will ever be expired. .PP The @@ -156,12 +163,12 @@ field specifies the upper bound on how long an article can be kept. No article will be kept longer then the number of days specified by this field. -All articles will be removed after then have been kept for +All matching articles will be removed after then have been kept for .I purge -days. +days, even if the Expires header indicates they should remain longer. If .I purge -is the word ``never'' then the article will never be deleted. +is the word ``never'', then the article will never be deleted. .PP If the line for .I classnum @@ -185,28 +192,31 @@ to some large number, like 365 days for a maximum article life of a year). To ignore any Expires header, set all three fields to the same value. .PP -For group based expiry, there must be exactly one line with a +For group-based expiry, there must be exactly one line with a .I pattern of ``*'' and a .I modflags of ``A'' \(em this matches all groups and is used to set the expiration default. -And for class base expiry, there can be exactly one line with a +And for class-based expiry, there can be exactly one line with a .I class of ``255'' \(em this matches all class and can be used to set the expiration default. In either case, it should be the first expiration line. .SH EXAMPLES -For class based expiry; +For class-based expiry: +.sp 1 .nf .in +0.5i ## How long to keep expired history /remember/:5 ## class 0 stay for two weeks 0:14:14:14 +.sp 1 .in -0.5i .fi -For group based expiry; +For group-based expiry: +.sp 1 .nf .in +0.5i ## How long to keep expired history Index: doc/man/filechan.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/filechan.8,v retrieving revision 1.6 diff -u -r1.6 filechan.8 --- doc/man/filechan.8 1998/04/09 15:16:06 1.6 +++ doc/man/filechan.8 2002/12/03 04:42:58 @@ -8,7 +8,7 @@ .BI \-d " directory" ] [ -.BI \-f " fields" +.BI \-f " num_fields" ] [ .BI \-m " mapfile" @@ -26,12 +26,12 @@ as a channel feed. (It is not a full exploder and does not accept commands; see .IR newsfeeds (5) -for a description of the difference and +for a description of the difference, and .IR buffchan (8) for an exploder program.) .PP .I Filechan -input is interpreted as a set of lines. +input is interpreted as a sequence of lines. Each line contains a fixed number of initial fields, followed by a variable number of filename fields. All fields in a line are separated by whitespace. @@ -46,13 +46,20 @@ opens it in append mode and tries to lock it and change the ownership to the user and group who owns the directory where the file is being written. +.PP +Because the time window in which a file is open is very small, complicated +flushing and locking protocols are not needed; a +.IR mv (1) +followed by a +.IR sleep (1) +for a couple of seconds is sufficient. .SH OPTIONS .TP -.B \-f +.B \-f num_fields The ``\fB\-f\fP'' flag may be used to specify a different number of initial fields. .TP -.B \-d +.B \-d directory By default, .I filechan writes its output into the directory @@ -60,13 +67,33 @@ The ``\fB\-d\fP'' flag may be used to specify a directory the program should change to before starting. .TP -.B \-p +.B \-p pidfile If the ``\fB\-p\fP'' flag is used, the program will write a line containing its process ID (in text) to the specified file. +.TP +.B \-m mapfile +A map file may be specified by using the ``\fB\-m\fP'' flag. +Blank lines and lines starting with a number sign (``#'') are ignored. +All other lines should have two host names separated by a colon. +The first field is the name that may appear in the input stream; +the second field names the file to be used when the name in the first +field appears. +For example, the following map file may be used to map the short +names used in the example below to the full domain names: .PP +.RS +.nf +# This is a comment +uunet:news.uu.net +foo:foo.com +munnari:munnari.oz.au +.fi +.RE +.SH EXAMPLES If .I filechan is invoked with ``\fB\-f 2\fP'' and given the following input: +.PP .RS .nf news/software/b/132 <1643@munnari.oz.au> foo uunet @@ -78,6 +105,7 @@ Then the file .I foo will have these lines: +.PP .RS .nf news/software/b/132 <1643@munnari.oz.au> @@ -88,6 +116,7 @@ the file .I munnari will have these lines: +.PP .RS .nf news/software/b/133 <102060@litchi.foo.com> @@ -98,36 +127,12 @@ and the file .I uunet will have these lines: +.PP .RS .nf news/software/b/132 <1643@munnari.oz.au> news/software/b/133 <102060@litchi.foo.com> comp/sources/unix/2002 <999@news.foo.com> -.fi -.RE -.PP -Because the time window in which a file is open is very small, complicated -flushing and locking protocols are not needed; a -.IR mv (1) -followed by a -.IR sleep (1) -for a couple of seconds is sufficient. -.TP -.B \-m -A map file may be specified by using the ``\fB\-m\fP'' flag. -Blank lines and lines starting with a number sign (``#'') are ignored. -All other lines should have two host names separated by a colon. -The first field is the name that may appear in the input stream; -the second field names the file to be used when the name in the first -field appears. -For example, the following map file may be used to map the short -names above to the full domain names: -.RS -.nf -# This is a comment -uunet:news.uu.net -foo:foo.com -munnari:munnari.oz.au .fi .RE .SH HISTORY Index: doc/man/getlist.1 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/getlist.1,v retrieving revision 1.7 diff -u -r1.7 getlist.1 --- doc/man/getlist.1 2002/08/10 18:51:31 1.7 +++ doc/man/getlist.1 2002/12/03 04:42:58 @@ -34,7 +34,7 @@ or .IR newsgroups . These values request the -.IR active (5), +.IR active , .IR active.times , .IR /distributions . or @@ -43,14 +43,16 @@ .SH OPTIONS .TP .B \-A -If the ``\fB\-A\fP'' flag is used, then the program tries to authenticates +If the ``\fB\-A\fP'' flag is used, then the program tries to authenticate +as per +.I passwd.nntp before issuing LIST command. .TP .B \-h If the ``\fB\-h\fP'' flag is used, then the program connects to the server on the specified host. The default is to connect to the server specified in the -.IR inn.conf (5) +.I inn.conf file. .PP If the @@ -94,4 +96,4 @@ This is revision \\$3, dated \\$4. .. .SH "SEE ALSO" -active(5), inn.conf(5), nnrpd(8), uwildmat(3). +active(5), active.times(5), inn.conf(5), nnrpd(8), uwildmat(3). Index: doc/man/grephistory.1 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/grephistory.1,v retrieving revision 1.9 diff -u -r1.9 grephistory.1 --- doc/man/grephistory.1 2002/11/05 04:12:02 1.9 +++ doc/man/grephistory.1 2002/12/03 04:42:59 @@ -36,7 +36,7 @@ queries the .IR dbz (3) index into the -.IR history (5) +.I history file for an article having a specified Message-ID. .PP If @@ -47,6 +47,9 @@ .I messageid is in the database, the program prints the token of the article and exits successfully. +.PP +Be sure to escape any special characters in the Message-ID from the shell. +Single quotes are recommended for this purpose. .SH OPTIONS .TP .B \-e @@ -76,8 +79,7 @@ successfully. This can happen when an article has been canceled, or if it has been expired but its history is still retained. -This is default behavior, which can be obtained by using -the ``\fB\-n\fP'' flag. +This is the default behavior. .TP .B \-q If the ``\fB\-q\fP'' flag is used, then no message is displayed. Index: doc/man/incoming.conf.5 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/incoming.conf.5,v retrieving revision 1.17 diff -u -r1.17 incoming.conf.5 --- doc/man/incoming.conf.5 2002/08/10 18:51:31 1.17 +++ doc/man/incoming.conf.5 2002/12/03 04:42:59 @@ -6,12 +6,12 @@ The file .I /incoming.conf consists of three types of entries: key/value, peer and group. -Comments are taken from the hash character ``#'' to the end of the line. +Comments are from the hash character ``#'' to the end of the line. Blank lines are ignored. All key/value entries within each type must not be duplicated. .PP Key/value entries are a keyword immediately followed by a colon, at least -one blank and a value. For example: +one blank and a value. For example: .PP .RS .nf @@ -19,8 +19,8 @@ .fi .RE .PP -A legal key contains nor blanks, nor colon, nor ``#''. -There are 3 different types of values: integers, booleans, and strings. +A legal key does not contains blanks, colons, nor ``#''. +There are 3 different types of values: integers, booleans, and strings. Integers are as to be expected. A boolean value is either ``true'' or ``false'' (case is significant). A string value is any other sequence of characters. If the string needs to contain whitespace, then it must be @@ -128,14 +128,14 @@ are allowed from this peer. (default=true) .TP .BI max-connections: -This key requires positive integer value. It defines the maximum number +This key requires a positive integer value. It defines the maximum number of connections allowed. A value of zero specifies an unlimited number of maximum connections (``unlimited'' or ``none'' can be used as synonym). (default=0) .TP .BI hold-time: -This key requires positive integer value. It defines the hold time before -close, if the connection is over max-connections. A value of zero +This key requires a positive integer value. It defines the hold time before +closing, if the connection is over max-connections. A value of zero specifies immediate close. (default=0) .TP .BI password: @@ -144,12 +144,13 @@ .TP .BI identd: This key requires a string value. It is used if you wish to require a peer's -user name through identd. (default=no identd) +user name retrieved through identd match the specified string. (default=no +identd) .TP .BI patterns: This key requires a string value. It is a list of -.IR newsfeeds (5) -style list of newsgroups which are to be accepted from this host. (default="*") +.IR newsfeeds (5)-style +list of newsgroups which are to be accepted from this host. (default="*") .TP .BI email: This key requires a string value. Reserved for future use. (default=empty) Index: doc/man/inews.1 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/inews.1,v retrieving revision 1.8 diff -u -r1.8 inews.1 --- doc/man/inews.1 2001/07/24 22:41:24 1.8 +++ doc/man/inews.1 2002/12/03 04:42:59 @@ -43,7 +43,7 @@ .SH DESCRIPTION .I Inews reads a Usenet news article (perhaps with headers) from -the named file or standard input if no file is given. +the named file, or standard input if no file is given. It adds some headers and performs some consistency checks. If the article does not meet these checks (for example, too much quoting of old articles, or posting to non-existent newsgroups) then @@ -52,7 +52,7 @@ .I inews sends the article to the local news server as specified in the -.IR inn.conf (5) +.I inn.conf file for distribution. .SH OPTIONS .TP @@ -76,9 +76,8 @@ The C News ``\fB\-N\fP'' flag is treated as the ``\fB\-D\fP'' flag. .TP .B \-O -The default Organization header will be provided if none is present -in the article or if the ``\fB\-o\fP'' flag is not used. -To prevent adding the default, use the ``\fB\-O\fP'' flag. +By default, an Organization header will be provided if none is present +in the article. To prevent adding the default, use the ``\fB\-O\fP'' flag. .TP .B \-p If the ``\fB\-p\fP'' flag is used, then the articles will be sent through the @@ -90,7 +89,7 @@ will reject any attempts to post control messages. .TP .B \-S -If a file named +By default, if a file named .I .signature exists in the user's home directory, .I inews @@ -107,7 +106,7 @@ Each of these flags takes a single parameter; if the value is more than one word (for example, almost all Subject lines) then quotes must be used to prevent the shell from splitting it into multiple words. -The options, and their equivalent header, are as follows: +The options, and their corresponding headers, are as follows: .RS .nf @@ -136,7 +135,7 @@ If .I is defined and the ``pathhost'' configuration parameter is specified in the -.IR inn.conf (5) +.I inn.conf file, then it will be added to the Path. Otherwise, if the ``server'' configuration parameter is specified, then the full domain name of the local host will be added to the Path.\} @@ -151,8 +150,8 @@ .I inews will try to mail the article to the moderator for posting. It will query the remote news server for a moderators listing. If -that doesn't succeed, it will fallback to using the local -.IR moderators (5) +that fails, it will fallback to using the local +.I moderators file to determine the mailing address. If no address is found, it will use ``moderatormailer'' in .IR inn.conf @@ -164,7 +163,7 @@ .IR NNTPsendpassword (3) routine to authenticate itself. In order to do this, the program will need read access to the -.IR passwd.nntp (5) +.I passwd.nntp file. This is typically done by having the file group-readable and making .I inews Index: doc/man/inncheck.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/inncheck.8,v retrieving revision 1.5 diff -u -r1.5 inncheck.8 --- doc/man/inncheck.8 1998/10/30 14:09:50 1.5 +++ doc/man/inncheck.8 2002/12/03 04:42:59 @@ -28,7 +28,7 @@ .I Inncheck examines various configuration files and databases and verifies things about them. Things verified depend on the file being checked, but generally -are things like permissions, ownership, syntax errors in config files etc. +are things like permissions, ownership, syntax errors in config files, etc. .PP .I Inncheck does not make changes to any files \(em it just reports what it @@ -37,7 +37,7 @@ The set of files checked may be restricted by using \fBfile\fP or \fBfile=value\fP arguments. For example, putting \fBincoming.conf\fP causes only the -.IR incoming.conf (5) +.I incoming.conf file to be checked. Using \fBincoming.conf=/tmp/incoming.conf\fP on the command line will cause .I inncheck @@ -61,6 +61,7 @@ overview.fmt nntpsend.ctl passwd.nntp + readers.conf .fi .RE .SH OPTIONS @@ -79,7 +80,7 @@ .B \-pedantic Use the ``\fB\-pedantic\fP'' option to get reports on things that are not necessarily wrong, but may indicate a bad configuration \(em such as -\fIinn.conf\fP(5) missing a key. +\fIinn.conf\fP missing a key. .TP .B \-f Use the ``\fB\-f\fP'' flag to have inncheck print the appropriate @@ -118,6 +119,15 @@ .RS .nf inncheck -perm active incoming.conf +.fi +.RE +.PP +To fix the permissions problems noted in the output of the above +command, modify it as follow: +.PP +.RS +.nf +inncheck -f -perm | sh .fi .RE .PP Index: doc/man/innfeed.1 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/innfeed.1,v retrieving revision 1.8 diff -u -r1.8 innfeed.1 --- doc/man/innfeed.1 2000/06/12 22:51:11 1.8 +++ doc/man/innfeed.1 2002/12/03 04:43:01 @@ -76,11 +76,9 @@ .\" .SH DESCRIPTION .PP -This man page describes version 1.0 of innfeed. -.PP .I Innfeed -implements the NNTP protocol for transferring news between computers. It -handles both the standard IHAVE protocol as well as the CHECK/TAKETHIS +implements the NNTP protocol for transferring news between computers. It +handles the standard IHAVE protocol as well as the CHECK/TAKETHIS streaming extension. Innfeed can feed any number of remote hosts at once and will open multiple connections to each host if configured to do so. The only limitations are the process limits for open file descriptors and memory. @@ -150,7 +148,9 @@ where it can store backlog files and a configuration file to describe which peers it should handle. .PP -The configuration file is described in innfeed.conf(5). The ``\fI\-c\fP'' +The configuration file is described in +.IR innfeed.conf (5). +The ``\fI\-c\fP'' option can be used to specify a different file. .PP For each peer (say, ``\fIfoo\fP''), innfeed manages up to 4 files in the @@ -180,7 +180,11 @@ file innd will write if innfeed is unavailable for some reason. When innfeed processes its own batch files it ignores everything after the first two whitespace separated fields, so moving the innd-created batch file to -the appropriate spot will work, even though the lines are longer. +the appropriate spot will work, even though the lines have extra fields. +.PP +The first field can also be a storage API token. The two types of lines can +be intermingled; innfeed will use the storage manager if appropriate and +otherwise treat the first field as a filename to read directly. .PP Innfeed writes its current status to the file ``\fIinnfeed.status\fP'' (or the file given by the ``\fI-S\fP'' option). This file contains details on @@ -207,15 +211,17 @@ state of the running system. .PP Innfeed will catch SIGHUP and will reload the config file. -See innfeed.conf(5) for more details. +See +.IR innfeed.conf (5) +for more details. .PP Innfeed will catch SIGCHLD and will close and reopen all backlog files. .PP Innfeed will catch SIGTERM and will do an orderly shutdown. .PP Upon receipt of a SIGUSR1 innfeed will increment the debugging level by -one, receipt of a SIGUSR2 will decrement it by one. The debugging level -starts at zero (unless the ``-d'' option it used), and no debugging +one; receipt of a SIGUSR2 will decrement it by one. The debugging level +starts at zero (unless the ``-d'' option it used), in which case no debugging information is emitted. A larger value for the level means more debugging information. Numbers up to 5 are currently useful. .\" @@ -225,7 +231,7 @@ .\" .SH SYSLOG ENTRIES .PP -There are 3 different categories of syslog entries for statistics. Host, +There are 3 different categories of syslog entries for statistics: Host, Connection and Global. .PP The Host statistics are generated for a given peer at regular intervals @@ -384,11 +390,12 @@ .TP .B \-d The ``\fI\-d\fP'' flag may be used to specify the initial logging level. All -debugging messages to to stderr (see the ``\fI\-l\fP'' flag below. +debugging messages go to stderr (which may not be what you want, see the +``\fI\-l\fP'' flag below). .TP .B \-e The ``\fI\-e\fP'' flag may be used to specify the size limit (in bytes) for the -\fI.output\fP backlog files innfeed creates. If the output file gets bigger +\fI\%.output\fP backlog files innfeed creates. If the output file gets bigger than 10% more than the given number, innfeed will replace the output file with the tail of the original version. The default value is 0, which means there is no limit. @@ -398,13 +405,13 @@ .TP .B \-l The ``\fI\-l\fP'' flag may be used to specify a different log file from -stderr. As innd starts innfeed with stderr attached to /dev/null using this -option can be useful in catching any abnormal error messages, or andy +stderr. As innd starts innfeed with stderr attached to /dev/null, using this +option can be useful in catching any abnormal error messages, or any debugging messages (all ``normal'' errors messages go to syslog). .TP .B \-M If innfeed has been built with mmap support, then the ``\fI\-M\fP'' flag -turns OFF the use of mmap(), otherwise it has no effect. +turns OFF the use of mmap(); otherwise it has no effect. .TP .B \-m The ``\fI\-m\fP'' flag is used to turn on logging of all missing @@ -441,12 +448,12 @@ unknown peer, then the peer name is taken to be the IP name too, and an association with it is created. Using this it is possible to only have the global defaults in the -.IR innfeed.conf (5) +.I innfeed.conf file, provided the peername as used by innd is the same as the ip name. Note that .I innfeed with ``\fI\-y\fP'' and no peer in -.IR innfeed.conf (5) +.I innfeed.conf would cause a problem that .I innfeed drops the first article. @@ -465,9 +472,9 @@ .PP When using the ``-x'' option, the config file entry's ``initial-connections'' field will be the total number of connections -created and used--no matter how many big the batch file, and no +created and used, no matter how many big the batch file, and no matter how big the ``max-connectiond'' field specifies. Thus a value -of 0 for ``initial-connections'', means nothing will happen in ``-x'' +of 0 for ``initial-connections'' means nothing will happen in ``-x'' mode. .PP Innfeed does not automatically grab the file out of out.going--this needs Index: doc/man/innfeed.conf.5 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/innfeed.conf.5,v retrieving revision 1.14 diff -u -r1.14 innfeed.conf.5 --- doc/man/innfeed.conf.5 2002/09/24 08:41:42 1.14 +++ doc/man/innfeed.conf.5 2002/12/03 04:43:02 @@ -20,7 +20,7 @@ is used to control the innfeed(1) program. It is a fairly free-format file that consists of three types of entries: \fIkey/value\fP, \fIpeer\fP and \fIgroup\fP. -Comments are taken from the hash character ``#'' to the end of the line. +Comments are from the hash character ``#'' to the end of the line. .PP \fIKey/value\fP entries are a keyword and a value separated by a colon (which can itself be surrounded by whitespace). For example: @@ -32,7 +32,7 @@ .RE .PP A legal -key starts with a letter and contains only letters, numbers and ``_'', +key starts with a letter and contains only letters, digits, and ``_'', ``-''. .LP There are 5 different type of values: integers, floating-point numbers, @@ -134,16 +134,18 @@ .fi .RE .PP -Innfeed ignores key/value pairs it is not interested in. Any config file -value that can be set via a command line option, -is not used if the command-line option is given. +Innfeed ignores key/value pairs it is not interested in. Some config file +values can be set via a command line option, in which case that setting +overrides the settings in the file. .PP Config files can be included in other config files via the syntax: +.sp 1 .nf .RS $INCLUDE filename .RE .fi +.sp 1 There is a maximum nesting depth of 10. .PP For a fuller example config file, see the supplied \fIinnfeed.conf\fP. @@ -215,22 +217,22 @@ .TP .B backlog-newfile-period This key requires a positive integer value. It specifies how many seconds -between checks for externally generated backlog files that are to be picked -up and processed. +before each checks for externally generated backlog files that are to be +picked up and processed. .\".................................................. .TP .B dns-retry -The key requires a positive integer value. It defines the number of seconds +This key requires a positive integer value. It defines the number of seconds between attempts to re-lookup host information that previous failed to be resolved. .TP .B dns-expire -The key requires a positive integer value. It defines the number of seconds -between refreshes of name to address DNS translation. This is so long running -processes don't get stuck with stale data, should peer ip addresses change.. +This key requires a positive integer value. It defines the number of seconds +between refreshes of name to address DNS translation. This is so long-running +processes don't get stuck with stale data, should peer ip addresses change. .TP .B close-period -The key requires a positive integer value. It is the maximum number of +This key requires a positive integer value. It is the maximum number of seconds a connection should be kept open. Some NNTP servers don't deal well with connections being held open for long periods. .TP @@ -289,14 +291,15 @@ value of 256. The default if this is not specified, is 0. .TP .B bindaddress -Which outgoing IPv4 address innfeed should bind the local end of its -connections to. +This key requires a string value. It specifies which outgoing IPv4 address +innfeed should bind the local end of its connections to. Must be in dotted-quad format (nnn.nnn.nnn.nnn). If not set, innfeed defaults to letting the kernel choose this address. The default value is unset. .TP .B bindaddress6 -Like \fBbindaddress\fP but for outgoing IPv6 connections. +This key requires a string value. It behave like \fBbindaddress\fP except +for outgoing IPv6 connections. .\".................................................. .SH "GLOBAL PEER DEFAULTS" .PP @@ -333,14 +336,14 @@ 1 means a maximum of 1 connection ]. .TP .B dynamic-method -This key requires a value between 0 and 3. It controls how connections -(up to max-connections) are opened up to the maximum specified by +This key requires an integer value between 0 and 3. It controls how connections +(up to max-connections) are opened, up to the maximum specified by \fBmax-connections\fP. In general (and specifically, with \fBdynamic-method\fP -0) a new connection is opened when the current number of connections is -below \fBmax-connections\fP, and an article is to be sent whilst no current +0), a new connection is opened when the current number of connections is +below \fBmax-connections\fP, and an article is to be sent while no current connections are idle. Without further restraint (i.e. using \fBdynamic-method\fP 0), in practice this means that \fBmax-connections\fP -connections are established whilst articles are being sent. Use of other +connections are established while articles are being sent. Use of other \fBdynamic-method\fP settings imposes a further limit on the amount of connections opened below that specified by \fBmax-connections\fP. This limit is calculated in different ways, depending of the value of @@ -360,17 +363,17 @@ .TP .B 1 maximize articles per second Connections are increased (up to \fBmax-connections\fP) and decreased so as -to maximize the number of articles per second sent, whilst using the fewest +to maximize the number of articles per second sent, while using the fewest connections to do this. .TP .B 2 set target queue length Connections are increased (up to \fBmax-connections\fP) and decreased so as to keep the queue of articles to be sent within the bounds set by \fBdynamic-backlog-low\fP and \fBdynamic-backlog-high\fP, -whilst using the minimum resource possible. +while using the minimum resources possible. As the queue will tend to fill if the site is not keeping up, this method ensures that the maximum number of articles are offered to the peer -whilst using the minimum number of connections to achieve this. +while using the minimum number of connections to achieve this. .TP .B 3 combination This method uses a combination of methods 1 and 2 above. For sites @@ -382,30 +385,30 @@ .RE .TP .B dynamic-backlog-low -This key takes a value between 0 and 100 and represents (as a percentage) -the low water mark for the host queue. When the host queue falls below -this level, when using \fBdynamic-method\fP 2 or 3, if 2 or more connections -are open, innfeed will attempt to drop connections to the host. An IIR -filter is applied to the value to prevent connection flap (see +This key requires an integer value between 0 and 100. It represents (as a +percentage) the low water mark for the host queue. If the host queue falls +below this level while using \fBdynamic-method\fP 2 or 3, and if 2 or more +connections are open, innfeed will attempt to drop connections to the host. +An IIR filter is applied to the value to prevent connection flap (see \fBdynamic-filter\fP). A value of 25.0 is recommended. This value must be smaller than \fBdynamic-backlog-high\fP. .TP .B dynamic-backlog-high -This key takes a value between 0 and 100 and represents (as a percentage) -the high water mark for the host queue. When the host queue rises above -this level, when using \fBdynamic-method\fP 2 or 3, if less than +This key requries an integer value between 0 and 100. It represents (as a +percentage) the high water mark for the host queue. If the host queue rises +above this level while using \fBdynamic-method\fP 2 or 3, and if less than \fBmax-connections\fP are open to the host, innfeed will attempt to open further connections to the host. An IIR filter is applied to the value to prevent connection flap (see \fBdynamic-filter\fP). A value of 50.0 is recommended. This value must be larger than \fBdynamic-backlog-low\fP. .TP .B dynamic-backlog-filter -This key takes a floating-point value between 0 and 1 which represents the +This key requires a floating-point value between 0 and 1. It represents the filter coefficient used by the IIR filter used to implement \fBdynamic-method\fP 2 and 3. The recommended value of this filter is 0.7, giving a time constant of 1/(1-0.7) articles. Higher values will result in slower -response to queue fullness changes, lower values with faster response. +response to queue fullness changes, lower values in faster response. .TP .B max-queue-size This key requires a positive integer value. It defines the maximum number @@ -427,7 +430,7 @@ this effectively turns off no-CHECK mode, as the percentage can never get above 100.0. If this value is too small, then the number of articles the peer rejects will get bigger (and your bandwidth will be wasted). A value -of 95.0 is usually pretty good. NOTE: In innfeed 0.9.3 and earlier this +of 95.0 usually works pretty well. NOTE: In innfeed 0.9.3 and earlier this value was in the range [0.0, 9.0]. .TP .B no-check-low: @@ -441,7 +444,7 @@ frequently go in and out of no-CHECK mode. If the difference is too big, then it will make it harder to get out of no-CHECK mode when necessary (wasting bandwidth). Keeping this to between 5.0 and 10.0 less than -\fBno-check-high\fP is usually pretty good. +\fBno-check-high\fP usually works pretty well. .TP .B no-check-filter This is a floating point value representing the time constant, in articles, Index: doc/man/innwatch.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/innwatch.8,v retrieving revision 1.6 diff -u -r1.6 innwatch.8 --- doc/man/innwatch.8 1998/09/17 06:12:28 1.6 +++ doc/man/innwatch.8 2002/12/03 04:43:02 @@ -18,7 +18,7 @@ seconds \(em examines the load average, and the number of free blocks and inodes on the spool partition, as described by its control file, -.IR innwatch.ctl (5). +.IR innwatch.ctl . .PP If the load gets too high, or the disk gets too full, it throttles the server. When the condition restores, it unblocks the server. @@ -34,13 +34,15 @@ .IR /innwatch.status . .SH OPTIONS .TP -.B \-l +.B \-l logfile To specify a log file to watch, other than the default of .IR news.crit , use the ``\fB\-l\fP'' flag. .TP -.B \-t -To change the period between check from the default, use the ``\fB\-t\fP'' +.B \-t seconds +To change the period between checks from the default from +.I inn.conf , +use the ``\fB\-t\fP'' flag. .SH HISTORY Written by Mike Cooper , with modifications by Index: doc/man/innwatch.ctl.5 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/innwatch.ctl.5,v retrieving revision 1.8 diff -u -r1.8 innwatch.ctl.5 --- doc/man/innwatch.ctl.5 2000/08/17 13:30:13 1.8 +++ doc/man/innwatch.ctl.5 2002/12/03 04:43:03 @@ -12,10 +12,17 @@ The file consists of a series of lines; blank lines and lines beginning with a number sign (``#'') are ignored. All other lines consist of seven fields, each preceded by a delimiting -character: +character, for example: +.sp 1 +.nf .RS :label:state:condition:test:limit:command:reason .RE +or +.RS +@label@state@condition@test@limit@command@reason +.RE +.fi .PP The delimiter can be any one of several non-alphanumeric characters that does not appear elsewhere in the line; there is no way to quote it to @@ -24,18 +31,18 @@ Each line can have a different delimiter; the first character on each line is the delimiter for that line. White space surrounding delimiters, except before the first, is ignored, -and does not form part of the fields, white space within fields is +and does not form part of the fields; white space within fields is permitted. All delimiters must be present. .PP -The first field is a label for the control line. +The first field is a label for this control line. It is used as an internal state indicator and in .I ctlinnd messages to control the server. -If omitted, the line number is used. +If this field is empty, the line number is used. .PP The second field specifies when this control line should be used. -It consists of a list of labels, +It consists of a list of labels and special indicators, separated by whitespace. If the current state matches against any of the labels in this field, @@ -43,16 +50,16 @@ The values that may be used are: .IP "\-" This line matches if the current state is the same as the label on -this line, or if the current state is ``run,'' the initial state. +this line, or if the current state is ``run'', the initial state. This is also the default state if this field is empty. .IP "+" -This line matches if the current state is ``run.'' +This line matches if the current state is ``run''. .IP "*" This line always matches. .IP "label" -This line matches if the current state is the specified ``label.'' +This line matches if the current state is the specified ``label''. .IP "\-label" -This line matches if the current state is not the specified ``label.'' +This line matches if the current state is not the specified ``label''. .PP The third field specifies a shell command that is invoked if this line matches. Do not use any shell filename expansion characters such as ``*'', ``?'', @@ -62,7 +69,7 @@ This gives the value of this control line, to be used below. If the command fails, the line is ignored. The command is executed with its current directory set to the news spool -directory, +articles directory, .IR . .PP The fourth field specifies the operator to use to test the value returned above. @@ -74,9 +81,11 @@ The fifth field specifies a constant with which to compare the value using the operator just defined. This is done by invoking the command: +.sp 1 .RS test value -operator constant .RE +.sp 1 The line is said to ``succeed'' if it returns true. .PP The sixth field specifies what should be done if the line succeeds, @@ -107,14 +116,14 @@ .IP go Causes .I innwatch -to send a ``go'' command to the server and to set the state to ``run.'' +to send a ``go'' command to the server and to set the state to ``run''. .IP exit Causes .I innwatch to exit. .PP .IP skip -The result of the control file is skipped for the current pass. +The remainder of the control file is skipped for the current pass. .PP The last field specifies the reason that is used in those .I ctlinnd @@ -159,6 +168,7 @@ The next three lines act as a group and should appear in the following order. It is easier to explain them, however, if they are described from the last up. +.PP .RS .nf !load!load hiload!loadavg!lt!5!go! @@ -166,6 +176,7 @@ /load/+/loadavg/ge/6/pause/loadav .fi .RE +.PP The final line causes the server to be paused if .I innwatch is in the ``run'' state and the load average rises to, or above, six. Index: doc/man/innxbatch.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/innxbatch.8,v retrieving revision 1.8 diff -u -r1.8 innxbatch.8 --- doc/man/innxbatch.8 2000/08/17 13:30:13 1.8 +++ doc/man/innxbatch.8 2002/12/03 04:43:03 @@ -30,50 +30,56 @@ .IR ctlinnd (8) command to flush the batchfile. .PP +Each file is removed after it has been successfully transferred. +.PP +If a communication error such as a +.IR write (2) +failure, or an unexpected reply from the remote server occurs, +.I innxbatch +will stop sending and leave all remaining files untouched for later retry. + + +.SH OPTIONS +.TP +.B \-t seconds .I Innxbatch normally blocks until the connection is made. To specify a timeout on how long to try to make the connection, use the ``\-t'' flag. -.br +.TP +.B \-T seconds To specify the total amount of time that should be allowed for article transfers, use the ``\-T'' flag. .br The default is to wait until an I/O error occurs, or all the articles have been transferred. If the ``\-T'' flag is used, the time is checked -just before an article is started; it will not abort a transfer that -is in progress. Both values are measured in seconds. -.PP -Each file is removed after it has been successfully transferred. -.PP -If a communication error such as a -.IR write (2) -failure, or an unexpected reply from the remote server occurs, -.I innxbatch -will stop sending and leave all remaining files untouched for later retry. -.PP -.PP +just before each article is started; it will not abort a transfer that +is in progress. +.TP +.B \-v Upon exit, .I innxbatch reports transfer and CPU usage statistics via .IR syslog (3). If the ``\-v'' flag is used, they will also be printed on the standard output. -.PP +.TP +.B \-D Use the ``\-D'' flag to print debugging information on standard error. This will show the protocol transactions between .I innxbatch and the NNTP server on the remote host. -.PP +.SH EXAMPLES A sample .I newsfeeds(5) entry to produce appropriate xbatch files (thanks to Karsten Leipold ): - +.sp 1 .nf nase\e :*\e :Tc,Wnb\e -.ds R$ +.ds R$ :\*(R$/batcher \e .ds R$ <$ac_cv_path_COMPRESS in config.cache> .ds P$ @@ -81,11 +87,11 @@ \*(P$/nase.\e$\e$)" \e nase.do.main .fi - +.sp 1 A sample script to invoke .I innxbatch(8) is: - +.sp 1 .nf #!/bin/sh ## SH script to send xbatches for a site, wrapped around innxbatch @@ -98,7 +104,7 @@ exit 1 fi - . /innshellvars + . /innshellvars site="$1"; host="$2"; shift; shift @@ -106,7 +112,6 @@ && sleep 5 \e && exec $NEWSBIN/innxbatch -v -D "$host" $* .fi - .SH HISTORY Written by Stefan Petri , modelled after .IR innxmit (8) Index: doc/man/innxmit.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/innxmit.8,v retrieving revision 1.12 diff -u -r1.12 innxmit.8 --- doc/man/innxmit.8 2001/04/23 03:26:55 1.12 +++ doc/man/innxmit.8 2002/12/03 04:43:03 @@ -44,7 +44,7 @@ connects to the NNTP server at the specified .I host (validating itself via -.IR passwd.nntp (5) +.IR passwd.nntp if possible) and sends it the articles specified in the batchfile named .IR file . @@ -62,7 +62,7 @@ .I directory. It is normally written by specifying the ``Wnm'' flags in the -.IR newsfeeds (5) +.I newsfeeds file. Each line in the batchfile should be in one of the following formats: .PP @@ -96,7 +96,7 @@ .B \-a If all articles were sent successfully, .I innxmit -will remove the batchfile, otherwise it will rewrite it to contain the +will remove the batchfile; otherwise it will rewrite it to contain the list of unsent articles. If no articles were sent or rejected, the file is left untouched. This can cause the batchfile to grow excessively large if many articles @@ -104,7 +104,7 @@ To always rewrite the batchfile, use the ``\fB\-a\fP'' flag. .TP .B \-c -In streaming mode a check of each message ID is still made to avoid sending +In streaming mode, a check of each message ID is still made to avoid sending articles already on the server. The ``\fB\-c\fP'' flag will, if streaming mode is supported, result in sending articles without checking. @@ -129,8 +129,8 @@ The ``\fB\-l\fP'' flag is used to turn on logging of reasons the remote gives for rejecting an article. .TP -.B \-P -To specify a port number other than the default, use the \-P flag. +.B \-P portnum +To specify a port number other than the default, use the ``\fB\-P\fP'' flag. .TP .B \-p If the ``\fB\-p\fP'' flag is given, then no connection is made and the batchfile @@ -155,16 +155,15 @@ Use the ``\fB\-s\fP'' flag to disable the attempt to negotiate the streaming mode extension. .TP -.B \-T +.B \-T seconds To specify the total amount of time that should be allowed for article transfers, use the ``\fB\-T\fP'' flag. The default is to wait until an I/O error occurs, or all the articles have been transferred. -If the ``\fB\-T\fP'' flag is used, the time is checked just before an article -is started; it will not abort a transfer that is in progress. -Both values are measured in seconds. +If the ``\fB\-T\fP'' flag is used, the time is checked just before each +article is started; it will not abort a transfer that is in progress. .TP -.B \-t +.B \-t seconds .I Innxmit normally blocks until the connection is made. To specify a timeout on how long to try to make the connection, use Index: doc/man/libinn.3 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/libinn.3,v retrieving revision 1.13 diff -u -r1.13 libinn.3 --- doc/man/libinn.3 2002/09/04 03:47:17 1.13 +++ doc/man/libinn.3 2002/12/03 04:43:04 @@ -158,8 +158,8 @@ uses the current time, process-ID, and fully-qualified domain name, which is passed as an argument and used if local host can not be resolved or it is different from ``domain'' set in -.IR inn.conf (5) -, to create a Message-ID header that is highly likely to be unique. +.IR inn.conf , +to create a Message-ID header that is highly likely to be unique. The returned value points to static space that is reused on subsequent calls. .PP .I HeaderCleanFrom @@ -201,7 +201,7 @@ .IR A ctive. .I CAopen opens the -.IR active (5) +.I active file for reading. It returns a pointer to an open FILE, or NULL on error. If a local or NFS-mounted copy exists, @@ -258,7 +258,7 @@ .IR D efault .IR D istribution. The -.IR distrib.pats (5) +.I distrib.pats file is consulted to determine the proper value for the Distribution header after all newsgroups have been checked. .I DDstart @@ -433,7 +433,7 @@ .I NNTPsendpassword sends authentication information to an NNTP server by finding the appropriate entry in the -.IR passwd.nntp (5) +.I passwd.nntp file. .I Server contains the name of the host; ``innconf->server'' will be used if Index: doc/man/libstorage.3 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/libstorage.3,v retrieving revision 1.18 diff -u -r1.18 libstorage.3 --- doc/man/libstorage.3 2002/08/10 18:51:31 1.18 +++ doc/man/libstorage.3 2002/12/03 04:43:05 @@ -5,7 +5,7 @@ .SH SYNOPSIS .nf .ta \w' unsigned long 'u -.B + #include "storage.h" .B "bool IsToken(const char *text);" @@ -83,13 +83,13 @@ .SH DESCRIPTION .I Libstorage is a library of common utility (the storage manager) routines for accessing -Usenet articles and related data independent of particular storage method, -and this is called storage api. +Usenet articles and related data independent of particular storage method; +this is known as the storage API. The storage manager's function is to isolate the applications from the individual methods and make the policy decisions as to which storage method should be called to store an article. .PP -One of the core concepts in the storage api is that articles are not +One of the core concepts in the storage API is that articles are not manipulated using the message-id or article number, but rather a token that uniquely identifies the article to the method that stored it. This may seem to be redundant since the message-id already is a unique identifier for the @@ -101,20 +101,20 @@ The ``OV'' function is to isolate the applications from the individual methods. .PP -All articles passed through storage api are assumed to be wire formatted. -Wire formatted means that ``\\CR\\LF'' at the end of lines, ``.'' at the -beginnig of lines and ``.\\CR\\LF'' at the end of article on nntp stream are not -stripped. This has performance win when transferring articles. -For ``tradspool'' method, wire format can be disabled. This is just for -compatibility which is needed by some old tool written for traditional -spool. +All articles passed through the storage API are assumed to be in wire +format. Wire format means ``\\CR\\LF'' at the end of lines, ``.'' at the +beginning of lines, and ``.\\CR\\LF'' at the end of article on NNTP stream +are not stripped. This has a performance win when transferring articles. +For the ``tradspool'' method, wire format can be disabled. This is just +for compatibility which is needed by some old tools written for +traditional spool. .PP .I IsToken checks to see if the text is formatted as a text token string. It returns TRUE if formatted correctly or returns FALSE if not. .PP .I TokenToText -converts token into text token string. +converts token into text string for output. .PP .I TextToToken converts text into token. @@ -127,21 +127,21 @@ .in +0.5i .nf SM_RDWR allow read/write open for storage - files(default is FALSE) + files (default is FALSE) SM_PREOPEN open all storage files at startup - time and keep them(default is FALSE) + time and keep them (default is FALSE) .fi .in -0.5i .sp 1 The .I value is the pointer which tells each type's value. -It returns TRUE if setup is successful or returns FALSE if not. +It returns TRUE if setup is successful, or FALSE if not. .PP .I SMinit calls the setup function for all of the configured methods based on .IR SMsetup . -This function should be called prior to all other storage api functions which +This function should be called prior to all other storage API functions which begin with ``SM'' except .IR SMsetup . It returns TRUE if initialization is successful or returns FALSE if not. @@ -155,22 +155,23 @@ .I arrived is specified, .I SMstore -use its value as article's arrival time or +uses its value as article's arrival time; otherwise .I SMstore -use current time for it. +uses the current time for it. .I SMstore returns token type as .IR type , or returns .I TOKEN_EMPTY -if article is not stored whichever error occures or simply does not match +if article is not stored because some error occurs or simply does not +match any .IR uwildmat (3) in -.IR storage.conf (5). +.IR storage.conf . .I SMstore fails if .I SM_RDWR -is not set to true with +has not been set to true with .IR SMsetup . .PP .I SMretrieve @@ -207,9 +208,9 @@ returns .I ARTHANDLE which should be used for the next query. -If NULL pointer +If a NULL pointer .I ARTHANDLE -is returned, no article is left to be queried. +is returned, no articles are left to be queried. If .I data of @@ -236,16 +237,16 @@ .I SMfreearticle should not be called as .I SMnext -frees allocated memory in itself. +frees allocated memory internally. .PP .I SMcancel -removes an article specified with +removes the article specified with .IR token . It returns TRUE if cancellation is successful or returns FALSE if not. .I SMcancel fails if .I SM_RDWR -is not set to true with +has not been set to true with .IR SMsetup . .PP .I SMprobe @@ -284,17 +285,17 @@ .PP .I SMshutdown calls the shutdown for each configured storage method and -then free any resources it has allocated for itself. +then frees any resources it has allocated for itself. .PP .I SMerrno and .I SMerrorstr -indicates the reason of the last error concerning storage manager. +indicate the reason of the last error concerning storage manager. .PP .I OVopen calls the setup function for configured method which is specified as \&``ovmethod'' in -.IR inn.conf (5). +.IR inn.conf . .I Mode is constructed from following. .sp 1 @@ -311,13 +312,13 @@ begin with ``OV''. .PP .I OVctl -probes or set some parameters for overview method. +probes or sets some parameters for overview method. .I Type is one of following. .sp 1 .in +0.5i .nf -OVGROUPBASEDEXPIRE setup how group based expiry is +OVGROUPBASEDEXPIRE setup how group-based expiry is done OVCUTOFFLOW do not add overview data, if the data is under lowest article @@ -334,48 +335,56 @@ retrieves specified newsgroup information from overview method. .PP .I OVgroupadd -informs overview method to specified newsgroup is added. +informs overview method that specified newsgroup is being added. .PP .I OVgroupdel -informs overview method to specified newsgroup is removed. +informs overview method that specified newsgroup is being removed. .PP .I OVadd stores an overview data. .PP .I OVcancel -requests overview method to delete an overview data specified with token. +requests the overview method delete overview data specified with token. .PP .I OVopensearch -requests overview method to prepare overview data retrieval. -The request range is determined by low and high. +requests the overview method prepare overview data retrieval. +The request range is determined by +.I low +and +.IR high . .PP .I OVsearch -retrieves information; article number, overview data or arrival time. +retrieves information; article number, overview data, or arrival time. .I OVsearch -should be called with NULL handle when it is the 1st time. -And subsequent +should be called with NULL handle when it is the first time; +subsequent .I OVsearch -should be called with the handle which is got at preveous +calls should use the handle returned by the previous call to .IR OVsearch . .I OVsearch returns TRUE, unless it reaches high which is specified by .IR OVopensearch . -Retrieved overview data are sorted by article number, and len is 0 if -there is no overview data for article. Note that the retrieved data -is not neccessarily null terminated, you should only rely on len octets -of overview data being present. +Retrieved overview data are sorted by article number, and +.I len +is ``0'' if there is no overview data for article. Note that the +retrieved data is not neccessarily null-terminated; you should only rely +on +.I len +octets of overview data being present. .PP .I OVclosesearch -frees all resources which is allocated by +frees all resources which have been allocated by .IR OVopensearch . .PP .I OVgetartinfo -retrieves overview data and token specified with artnum. +retrieves overview data and token specified with +.IR artnum . .PP .I OVexpiregroup expires overview data for the newsgroup. .I OVexpiregroup -checks the existense of the article and purge overview data if it's gone. +checks the existense of the article and purges overview data if the +article no longer exists. If ``groupbaseexpiry'' in .I inn.conf is true, @@ -383,7 +392,7 @@ also expires articles. .PP .I OVclose -frees all resources which is used by overview method. +frees all resources which are used by the overview method. .SH HISTORY Written by Katsuhiro Kondou for InterNetNews. .de R$ Index: doc/man/mailpost.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/mailpost.8,v retrieving revision 1.5 diff -u -r1.5 mailpost.8 --- doc/man/mailpost.8 2002/08/10 18:51:31 1.5 +++ doc/man/mailpost.8 2002/12/03 04:43:05 @@ -1,5 +1,5 @@ .\" -*- nroff -*- -.TH MAILPOST 1 +.TH MAILPOST 8 .SH NAME mailpost \- feed an email message into a news group .SH SYNOPSIS @@ -30,60 +30,70 @@ The .I mailpost program reads a properly formatted email message from stdin and feeds it to -inews for posting to a news server. Before feeding the article to inews it -checks that the article has not been seen before, and it changes some headers -(cleans some address headers up and puts ``X-'' in front of unknown headers). +inews for posting to a news server. +.I newsgroups +is a whitespace-separated list of group names to which to post the article. +.PP +Before feeding the article to inews, it checks that the article has not +been seen before, and it changes some headers (cleans up some address +headers and puts ``X-'' in front of unknown headers). .PP If the article has been seen before .RI ( mailpost -records the message-id of all articles is handles), the the article will be +records the message-id of each articles it handles), then the article will be silently dropped. Other errors will cause the article to be mailed to the newsmaster. .PP -Normally mailpost is run by sendmail via an alias entry: +Normally mailpost is run by +.IR sendmail (8) +via an alias entry: .PP .RS .nf -.ds R$ /bin +.ds R$ local-mail-wreck-bikes: "|\*(R$/mailpost -d local local.mail.rec.bicycles.racing" .fi .RE -.PP -.I newsgroups -is a list of group name separated by white spaces. .SH OPTIONS .TP -.B \-a +.B \-a addr If the ``\fB\-a\fP'' flag is used the value given is added to the article as an Approved header. .TP -.B \-b -IF the ``\fB\-b\fP'' flag is used, then it defines the location of the database +.B \-b database +If the ``\fB\-b\fP'' flag is used, then it defines the location of the database used to store the message ids of articles sent on. This is to prevent articles looping around if a news to mail gateway sends them back here. This option may be required if the mailpost process doesn't have write access to the news tmp -directory (the value of \fBpathtmp\fP in \fBinn.conf(5)\fP. +directory (the value of \fBpathtmp\fP in \fBinn.conf\fP). .TP -.B \-c -If the ``\fB\-c\fP'' flag is used the sleep time before posting. Until -timeout, if duplicated message are received, original message is considered as -a crossposted article and its Newsgroup header is update to be so. +.B \-c wait-time +The ``\fB\-c\fP'' flag indicates a length of time to sleep before +posting. If duplicate messages are received in this interval (by any +instance of +.I mailpost +using the same database), the article is only posted once, but with +.I Newsgroups +header modified to crosspost the article to all indicated groups. .TP -.B \-d +.B \-d distribution If the ``\fB\-d\fP'' flag is used the value given is added to the article as a Distribution header. .TP -.B \-f +.B \-f addr The ``\fB\-f\fP'' flag is a synonym for the ``\fB\-r\fP'' flag. .TP -.B \-m +.B \-m mailing-list If the ``\fB\-m\fP'' flag is used the value given is added to the articles in a -Mailing-List header, if a Mailing-List header doesn't already exist. +.I Mailing-List +header, if such a header doesn't already exist. .TP -.B \-r -If the ``\fB\-r\fP'' flag is used the program will use the given address -as the Path header, if no other value can be determined. +.B \-r addr +A heuristic is used to determine a reasonable value for the +.I Path +header. The ``\fB\-r\fP'' flag indicates what to use if no other value +can be determined. .SH HISTORY Written by Paul Vixie long ago and then hacked up by James Brister for INN integration. Index: doc/man/makeactive.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/makeactive.8,v retrieving revision 1.7 diff -u -r1.7 makeactive.8 --- doc/man/makeactive.8 1999/08/27 05:32:12 1.7 +++ doc/man/makeactive.8 2002/12/03 04:43:05 @@ -5,3 +5,5 @@ .SH SYNOPSIS .IR makeactive (8) is obsolete. +.SH "SEE ALSO" +active(5) Index: doc/man/makedbz.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/makedbz.8,v retrieving revision 1.1 diff -u -r1.1 makedbz.8 --- doc/man/makedbz.8 1999/08/27 05:32:13 1.1 +++ doc/man/makedbz.8 2002/12/03 04:43:05 @@ -27,11 +27,10 @@ to specify a different name, use the ``\fB\-f\fP'' flag. .SH OPTIONS .TP -.B \-f +.B \-f file If the ``\fB\-f\fP'' flag is used, then the database files are named -.I file.dir -, -.I file.index +.IR file.dir , +.IR file.index , and .IR file.hash . If the ``\fB\-f\fP'' flag is not used, then a temporary link to the name @@ -45,7 +44,7 @@ .TP .B \-i To ignore the old database use the ``\fB\-i\fP'' flag. -Using the ``\fB\-o\fP'' or ``\fB\-s\fP'' flag implies the ``\fB\-i\fP'' flag. +Using the ``\fB\-o\fP'' or ``\fB\-s\fP'' flags implies the ``\fB\-i\fP'' flag. .TP .B \-o If the ``\fB\-o\fP'' flag is used, then the link is not made and any existing @@ -54,11 +53,11 @@ .I makedbz will use it to determine the size of the new database. .TP -.B \-s +.B \-s size The program will also ignore any old database if the ``\fB\-s\fP'' flag is used to specify the approximate number of entries in the new database. Accurately specifying the size is an optimization that will create a more -efficient database. +efficient database. Size is measured in key-value pairs (i.e., lines). (The size should be the estimated eventual size of the file, typically the size of the old file.) For more information, see the discussion of Index: doc/man/mod-active.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/mod-active.8,v retrieving revision 1.1 diff -u -r1.1 mod-active.8 --- doc/man/mod-active.8 1998/10/28 16:05:56 1.1 +++ doc/man/mod-active.8 2002/12/03 04:43:05 @@ -19,7 +19,7 @@ .B innd from updating the active file but also locks against other instances of -.B mod-active. +.BR mod-active . .PP The input to .B mod-active @@ -29,9 +29,9 @@ or .B actsync commands. Every line which contains the string "ctlinnd newgroup", -"ctlinnd rmgroup" or "ctlinnd changegroup", optionally preceded by +"ctlinnd rmgroup", or "ctlinnd changegroup", optionally preceded by whitespace and/or the path to -.B ctlinnd, +.BR ctlinnd , is noted for the update. Redundant commands, such as a newgroup directive for a group that already exists, are silently ignored. All other lines in the input are also silently ignored. @@ -78,6 +78,7 @@ .. .SH "SEE ALSO" .IR active (5), +.IR active.times (5), .IR actsync (8), .IR ctlinnd (8), .IR innd (8). Index: doc/man/moderators.5 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/moderators.5,v retrieving revision 1.7 diff -u -r1.7 moderators.5 --- doc/man/moderators.5 2002/08/10 18:51:31 1.7 +++ doc/man/moderators.5 2002/12/03 04:43:05 @@ -4,24 +4,29 @@ moderators \- submission addresses for moderated newsgroups .SH DESCRIPTION When an unapproved article is posted locally to a moderated newsgroup, -rather than being passed off to +it is not passed off to .IR innd (8) -for normal handling, it's instead sent via e-mail to the submission +for normal handling; instead it's instead sent via e-mail to the submission address for that newsgroup. The file .I /moderators lists the submission addresses for moderated newsgroups. This file is used by .IR nnrpd "(8), " inews (1), and any other program that uses the GetModeratorAddress() routine (see -.IR libinn (3).) +.IR libinn (3)). .PP The moderators file is a list of associations between .IR uwildmat(3) patterns matching newsgroups and the submission address for those newsgroups. Blank lines and lines starting with a number sign (``#'') are ignored. -All other lines should consist of those two fields separated by a colon. +All other lines should consist of two fields separated by a colon. .PP +The first field specifies the group or groups to match using +.IR uwildmat(3). +The first matching line is used, so more specific patterns should occur +earlier than general patterns. +.PP The second field, the submission address, may have at most one .I %s anywhere in it; if present, this will be replaced by the name of the @@ -54,7 +59,7 @@ .fi .RE Periods are converted to dashes for historical reasons, from back in the -days when periods in the local part of addresses may not be handled +days when periods in the local part of addresses were not always handled correctly. It's probably no longer necessary, but so much now depends on it that it can't be easily changed. .PP @@ -69,8 +74,8 @@ the details to that address. .PP Given that, the only thing you should have to add to the sample file under -normal circumstances are the forwarding addresses for local or limited -distribution moderated groups. +normal circumstances are the forwarding addresses for local or +limited-distribution moderated groups. .SH HISTORY Written by Rich $alz for InterNetNews. .de R$ Index: doc/man/news.daily.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/news.daily.8,v retrieving revision 1.13 diff -u -r1.13 news.daily.8 --- doc/man/news.daily.8 2000/10/12 10:40:58 1.13 +++ doc/man/news.daily.8 2002/12/03 04:43:06 @@ -32,8 +32,8 @@ should be run once a day, typically out of .IR cron (8). It may be run more often, but such invocations should at least use the -\&``norotate'' keyword to prevent the log files from being processed -and rotated too fast. +\&``norotate'' keyword (or perhaps the \&``notdaily'' keyword) to +prevent the log files from being processed and rotated too fast. .PP The .IR shlock (1) @@ -102,7 +102,7 @@ is invoked to remove old overview database, if .I enableoverview is set in -.IR inn.conf (5). +.IR inn.conf . Using this keyword disables this function. .TP .I noexplog @@ -118,10 +118,10 @@ output. It has no effect if the ``noexpire'' keyword is used. .TP -.IR flags= "'expire\ args'" +.IR flags= "'args\ for\ expire'" By default, .I expire -is invoked with the an argument of ``\-v1''. +is invoked with argument ``\-v1''. Using this keyword changes the arguments to those specified. Be careful to use quotes if multiple arguments are needed. This keyword has no effect if the ``noexpire'' keyword is used. @@ -147,9 +147,9 @@ This keyword disables the .IR ctlinnd (8) renumber operation. -Normally, the low-water mark for all newsgroups (see +Normally, the low-water marks for all newsgroups (see .IR active (5)) -is reset. +are reset. .TP .I norm By default, any socket @@ -173,7 +173,7 @@ keyword is not needed. This is the case that the server runs only for feeder(no reader). .TP -.IR expireoverflags= "'expireover\ args'" +.IR expireoverflags= "'args\ for\ expireover'" If the ``expireover'' keyword is used, this keyword may be used to specify the flags to be passed to .IR expireover . @@ -196,7 +196,7 @@ If the ``lowmark'' keyword is used, .IR ctlinnd (8) lowmark is used for renumbering -.IR active (5). +.IR active . Normal .IR ctlinnd (8) renumber operation will take long time. With ``lowmark'' keyword this will Index: doc/man/news2mail.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/news2mail.8,v retrieving revision 1.2 diff -u -r1.2 news2mail.8 --- doc/man/news2mail.8 1998/12/09 15:53:54 1.2 +++ doc/man/news2mail.8 2002/12/03 04:43:06 @@ -30,13 +30,13 @@ name and is what innd uses (i.e. the site field of the entry in the newsfeeds file). The second field is the actual email address to send the article to. In the email message, the ``To'' header will have the mailing list name (i.e. the -first field) +first field). .PP .RS .nf -# list-name address -big-red-ants@ucsd.edu big-red-ants-digest@ucsd.edu -news-software@ucsd.edu news-software-digest@ucsd.edu +# list-name address +big-red-ants@ucsd.edu big-red-ants-digest@ucsd.edu +news-software@ucsd.edu news-software-digest@ucsd.edu .fi .RE .PP @@ -44,7 +44,7 @@ .PP .RS .nf -.ds R$ /bin +.ds R$ n2m!:!*:Tc,Ac,Wn*:\*(R$/news2mail big-red-ants@ucsd.edu:rec.pets.redants.*:Tm:n2m! @@ -58,8 +58,8 @@ Date, Organization and Message-ID in there. It add a To header with the mailing list name in it. .SH HISTORY -news2mail was written by Brian Kantor. This man pagewas written by James -Brister +news2mail was written by Brian Kantor. This man page was written by James +Brister. .de R$ This is revision \\$3, dated \\$4. .. Index: doc/man/newslog.5 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/newslog.5,v retrieving revision 1.8 diff -u -r1.8 newslog.5 --- doc/man/newslog.5 2001/05/14 04:16:47 1.8 +++ doc/man/newslog.5 2002/12/03 04:43:07 @@ -7,7 +7,8 @@ directory and have a ``.log'' extension. Several versions are usually kept with an additional extension such as ``.1'', ``.2'', etc. \(em the higher the number, the older the log. -The older versions are compressed. +The older versions may be compressed and thus may have a ``.1.gz'', +``.2.gz'', etc. extension. .PP The .I scanlogs @@ -26,6 +27,7 @@ .PP The following files will only accumulate data under the direction of .IR control.ctl (5): +.sp 1 .RS control.log miscctl.log @@ -33,9 +35,11 @@ rmgroup.log unwanted.log .RE +.sp 1 In order to create these files, the ``message'' and ``action'' fields of .I control.ctl should be chosen from the following table: +.sp 1 .RS .nf .ta \w'newgroup 'u +\w'doit=newgroup 'u @@ -50,22 +54,26 @@ ``other'' log=miscctl Log message .fi .RE +.sp 1 Here, ``other'' refers to any other control message such as: +.sp 1 .RS +.nf checkgroups ihave sendme sendsys senduuname version +.fi .RE .PP -The following is a list of log files. +The following is a list of log files: .TP .I control.log This file maintains a count of the number of newgroup and rmgroup control messages seen for each newsgroup. -The count is of the number of control messages with identical +The count is of the number of control messages with the indicated arguments, regardless if they were actually processed. All control arguments, including invalid ones, are counted. This file is updated by @@ -80,7 +88,7 @@ spawned by .IR innd (8), such as channel feeds configured in -.IR newsfeeds (5). +.IR newsfeeds . This file should normally be empty. .I Scanlogs will print the entire contents of this log file if it is non-empty. @@ -124,15 +132,18 @@ This log file should be empty. .I Scanlogs will print the entire contents of this log file if it is non-empty. -You should have the following line in your -.IR syslog.conf (5) -file. (A typical entry is shown; it should agree with -.I ) +You should have the following line in your system +.I syslog.conf +file, using a tab character for the delimiter: +.sp 1 .RS .RS news.crit /news.crit .RE .RE +.sp 1 +(A typical entry is shown; it should agree with +.I .) .TP .I news.err All major error messages issued by @@ -142,16 +153,18 @@ This log file should be empty. .I Scanlogs will print the entire contents of this log file if it is non-empty. -You should have the following line in your -.IR syslog.conf (5) -file: -(A typical entry is shown; it should agree with -.I ) +You should have the following line in your system +.I syslog.conf +file, using a tab character for the delimiter: +.sp 1 .RS .RS news.err /news.err .RE .RE +.sp 1 +(A typical entry is shown; it should agree with +.I .) .TP .I news.notice All standard error messages and status messages issued by @@ -164,16 +177,17 @@ script .IR innreport (8) to summarize this file. -You should have the following line in your -.IR syslog.conf (5) -file: -(A typical entry is shown; it should agree with -.I ) +You should have the following line in your system +.I syslog.conf +file, using a tab character for the delimiter: +.sp 1 .RS .RS news.notice /news.notice .RE .RE +(A typical entry is shown; it should agree with +.I .) .TP .I nntpsend.log The @@ -210,4 +224,5 @@ innd(8), news.daily(8), nntpsend(8), -newslog(8). +newslog(8), +syslog.conf(5). Index: doc/man/nnrpd.track.5 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/nnrpd.track.5,v retrieving revision 1.3 diff -u -r1.3 nnrpd.track.5 --- doc/man/nnrpd.track.5 1998/04/09 15:16:12 1.3 +++ doc/man/nnrpd.track.5 2002/12/03 04:43:07 @@ -4,14 +4,19 @@ nnrpd.track \- file to specify hosts to be tracked by nnrpd. .SH DESCRIPTION This file, which is located in -.I /etc +.I , specifies which hosts are to have their activities recorded during an .I nnrpd session. The .I nnrpd -server reads it then first spawned by -.IR innd . +server reads it when first spawned by +.IR innd , +provided +.I readertrack +in +.I inn.conf +is true; otherwise this file is not used. .PP Entries consist of one host specification per line, each line having two fields, separated by a colon: Index: doc/man/nntpget.1 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/nntpget.1,v retrieving revision 1.2 diff -u -r1.2 nntpget.1 --- doc/man/nntpget.1 1998/01/28 04:07:57 1.2 +++ doc/man/nntpget.1 2002/12/03 04:43:07 @@ -61,9 +61,9 @@ .IR file . .TP .B \-u -The ``\fB\-u\fP'' option is the same except that if the transfer succeeded, the -file will be updated with a statistics line, modifying its timestamp so that -it can be used in later invocations. +The ``\fB\-u\fP'' option is like ``\fB\-f\fP'' except that if the transfer +succeedes, the file will be updated with a statistics line, modifying its +timestamp so that it can be used in later invocations. .TP .B \-t If the ``\-t'' option is used, then the specified @@ -71,13 +71,13 @@ is used as the time and date parameter to the ``newnews'' command. .TP .B \-n -If either the ``\fB\-t\fP'' or ``\fB\-f\fP'' options are used, then +If either the ``\fB\-u\fP'' or ``\fB\-f\fP'' options are used, then the ``\fB\-n\fP'' option may be used to specify a newsgroup list. The default is ``*''. .TP .B \-d The ``\fB\-d\fP'' option may be -used to specify a distribution list when using the ``\fB\-t\fP'' +used to specify a distribution list when using the ``\fB\-u\fP'' or ``\fB\-f\fP'' options. The default is no distribution list. .SH HISTORY Index: doc/man/nntpsend.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/nntpsend.8,v retrieving revision 1.11 diff -u -r1.11 nntpsend.8 --- doc/man/nntpsend.8 2001/12/07 07:26:28 1.11 +++ doc/man/nntpsend.8 2002/12/03 04:43:07 @@ -65,7 +65,7 @@ If no such pairs are given, .I nntpsend defaults to the information given in the -.IR nntpsend.ctl (5) +.I nntpsend.ctl config file. .PP The @@ -88,7 +88,7 @@ .IR /nntpsend.log . In order to keep from overwhelming the local system, .I nntpsend -waits five seconds before spawned each child. +waits five seconds before spawning each child. .PP .I Nntpsend expects that the batchfile for a site is named @@ -122,7 +122,7 @@ The ``\-D'' flag does the same and it passes ``\-d'' to all .I innxmit -invocations which in turn causes +invocations, which in turn causes .I innxmit to go into debug mode. .TP @@ -133,13 +133,13 @@ .IR shlock (1) and does not lock batch files. .TP -.B \-s +.B \-s size If the ``\-s'' flag is used, then .IR shrinkfile (1) will be invoked to perform a head truncation on the batchfile and the flag will be passed to it. .TP -.B \-w +.B \-w delay If the ``\-w'' flag is used, then .I nntpsend waits for @@ -152,7 +152,7 @@ ``\fB\-r\fP'', \``\fB\-S\fP'', ``\fB\-T\fP'' and ``\fB\-t\fP'' flags are passed on to the child .I innxmit -program. ``\-N'' flag is passed as ``\fB\-s\fP'' flag on to the child +program. The ``\-N'' flag is passed as ``\fB\-s\fP'' flag to the child .I innxmit program. See @@ -166,7 +166,9 @@ .I nntpsend with this flag in case a site cannot be reached for an extended period of time. .SH EXAMPLES -With the following control file: +With the following +.IR nntpsend.ctl (5) +control file: .PP .RS .nf Index: doc/man/nntpsend.ctl.5 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/nntpsend.ctl.5,v retrieving revision 1.6 diff -u -r1.6 nntpsend.ctl.5 --- doc/man/nntpsend.ctl.5 1998/04/09 15:16:14 1.6 +++ doc/man/nntpsend.ctl.5 2002/12/03 04:43:07 @@ -3,7 +3,7 @@ nntpsend.ctl \- list of sites to feed via nntpsend .SH DESCRIPTION The file -.I <--prefix=PREFIX at configure>/nntpsend.ctl +.I /nntpsend.ctl specifies the default list of sites to be fed by .IR nntpsend (8). .PP @@ -13,7 +13,7 @@ All other lines should consist of four fields separated by a colon. .PP The first field is the name of the site as specified in the -.IR newsfeeds (5) +.I newsfeeds file. .PP The second field should be the hostname or IP address of the remote site. @@ -21,17 +21,18 @@ The third field, if non-empty, specifies the default head truncation size of site's batchfile. If this field is empty, no truncation is performed. -If this field is of the form ``\fRmaxsize-truncsize\fP'' then it is passed to +This field may be of the form ``\fRmaxsize-truncsize\fP'', in which case it +is passed to .I shrinkfile -as ``\fR\-m maxsize \-s truncsize\fP'', otherwise -is of the form ``\fRtruncsize\fP'' then it is passed as ``\fR\-s truncsize\fP''. +as ``\fR\-m maxsize \-s truncsize\fP''; otherwise it is of the form +``\fRtruncsize\fP'', in which case it is passed as ``\fR\-s truncsize\fP''. .PP The fourth field specifies some default flags passed to .IR innxmit (8). The flag ``\-a'' is always given to .I innxmit -and need not appear hear. -If no ``\-t timeout'' flag is given in this field and on the +and need not appear here. +If no ``\-t timeout'' flag is given in this field or on the .I nntpsend command line, ``\-t\ 180'' will be given to .IR innxmit . Index: doc/man/overchan.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/overchan.8,v retrieving revision 1.10 diff -u -r1.10 overchan.8 --- doc/man/overchan.8 2000/08/17 13:30:16 1.10 +++ doc/man/overchan.8 2002/12/03 04:43:08 @@ -5,7 +5,7 @@ .SH SYNOPSIS .B overchan [ -.B \- \&| file +.BR file \ ... ] .SH DESCRIPTION .I Overchan @@ -17,27 +17,29 @@ .I Overchan was originally designed to be used by InterNetNews or the C News ``mkov'' packages to update the database as the articles come in. -For current inn, the database is stored by overview method. +For current INN, the database is stored in a selected overview method. This can be done within .IR innd (8) -but, still +itself, but .IR overchan (8) -can do this, if +can be used instead, if .I is ``true'' and appropriate setup is done in -.IR newsfeeds (5). -file, for example: +.IR newsfeeds , +for example: .PP .RS overview!:*:Tc,WnteO:/overchan .RE .PP -This data consists of a line of text, separated into four parts by a space. +.I Overchan +input data consists of a line of text, separated into four parts by a space. The first part is a token for the article. The second part is time when the article was received. -The third part is time when the article will be expired(which represents -Expires header.) +The third part is time when the article will be expired (which represents +the Expires header). The fourth part is the data to be stored. +.PP The data in the overview files should be expired by running .IR expireover (8). This is normally done by adding the ``expireover'' flag to the Index: doc/man/overview.fmt.5 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/overview.fmt.5,v retrieving revision 1.9 diff -u -r1.9 overview.fmt.5 --- doc/man/overview.fmt.5 2002/01/05 20:45:25 1.9 +++ doc/man/overview.fmt.5 2002/12/03 04:43:08 @@ -16,8 +16,8 @@ colon; this indicates that the header should appear as well as its value. .PP If this file is changed, new overview records will be constructed with -the modified format. If it is desired to update existing records, it is -necessary to rebuild the existing overview database using +the modified format. If it is desired that existing records be updated to +the new format, it is necessary to rebuild the overview database using .IR makehistory (8) after removing all existing overview files. .PP @@ -27,6 +27,7 @@ .PP The default file, show below, is compatible with Geoff Collyer's ``nov'' package: +.PP .RS .nf Subject: Index: doc/man/prunehistory.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/prunehistory.8,v retrieving revision 1.7 diff -u -r1.7 prunehistory.8 --- doc/man/prunehistory.8 1998/04/09 15:16:15 1.7 +++ doc/man/prunehistory.8 2002/12/03 04:43:08 @@ -1,7 +1,7 @@ .\" $Revision: 1.7 $ .TH PRUNEHISTORY 8 .SH NAME -prunehistory \- remove file names from Usenet history file +prunehistory \- remove tokens from Usenet history file .SH SYNOPSIS .B prunehistory [ @@ -12,27 +12,24 @@ ] .SH DESCRIPTION .I Prunehistory -modifies the -.IR history (5) -text file to ``remove'' a set of filenames from it. -The filenames are removed by overwriting them with spaces, so that the -size and position of any following entries does not change. +modifies a +.IR history (5)-format +text file to ``remove'' a set of tokens from it. +The tokens are removed by overwriting them with spaces, so that the +size and position of any following entries does not change. This has an +effect similar to expiring the article, in that it is still mentioned in +the history database but cannot be retrieved. .PP .I Prunehistory reads the standard input. The input is taken as a set of lines. Blank lines and lines starting with a number sign (``#'') are ignored. All other lines are should consist of a Message-ID followed by zero or -more filenames. +more other fields (which are ignored). .PP The Message-ID is used as the .IR dbz (3) key to get an offset into the text file. -If no filenames are mentioned on the input line, then all filenames in -the text are ``removed.'' -If any filenames are mentioned, they are converted into the history file -notation. -If they appear in the line for the specified Message-ID then they are removed. .PP Since .IR innd (8) @@ -53,7 +50,7 @@ is used as a filter for other programs such as .IR reap . .TP -.B \-f +.BI \-f " filename" The default name of the history file is .IR /history ; to specify a different name, use the ``\-f'' flag. Index: doc/man/pullnews.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/pullnews.8,v retrieving revision 1.3 diff -u -r1.3 pullnews.8 --- doc/man/pullnews.8 2000/04/13 14:27:33 1.3 +++ doc/man/pullnews.8 2002/12/03 04:43:08 @@ -57,12 +57,12 @@ Graham's site http://www.connect.net/gbarr/ .SH OPTIONS .TP -.B \-c +.BI \-c " config" Normally the config file is stored in $HOME/.pullnews for the user running the .I pullnews program. The ``\fB\-c\fP'' flag lets you change that. .TP -.B \-g +.BI \-g " groups" The ``\fB\-g\fP'' flag specifies a collection of groups to get. The value must be a single argument with commas between group names. Each group must be defined in the config file. @@ -71,18 +71,19 @@ .B \-h The ``\fB\-h\fP'' flag just prints usage. .TP -.B \-p -The ``\fB\-p\fP'' flag can be used to change connecting port other than 119. +.BI \-p " port" +The ``\fB\-p\fP'' flag can be used to change connecting port to +something other than 119. .TP .B \-q The ``\fB\-q\fP'' flag can be used to make things run more quietly. .TP -.B \-r +.BI \-r " file" The ``\fB\-r\fP'' flag tells .I pullnews -to create an rnews-compatible file, instead of feeding article. +to create an rnews-compatible file, instead of feeding articles. .TP -.B \-s +.BI \-s " downstream-server" Normally .I pullnews will feed the articles it retrieves to the news server running on @@ -93,7 +94,7 @@ .I pullnews is a series of sets of lines describing the upstream hosts to connect to and the newsgroups to get articles from. A host line has no leading white space and -just has the name of the host to connect to. Group lines com after a host line +just has the name of the host to connect to. Group lines come after a host line and have leading white space followed by the group name. .PP .I pullnews @@ -102,6 +103,7 @@ downstream server. .PP A sample configuration file might look like: +.PP .RS .nf # Format group date high @@ -116,7 +118,9 @@ .PP The group entries for the two rec.* groups have been updated by an earlier run by -.IR pullnews . +.IR pullnews , +whereas the two comp.* groups were just inserted by the user and have +not yet been checked. .SH HISTORY pullnews was written by James Brister for INN. .de R$ @@ -126,7 +130,7 @@ .SH BUGS .I pullnews is very simple and is lacking in more sophisticated features (like killing -articles based on user-defined conditions) that better pull feeder most +articles based on user-defined conditions) that better pull feeders most certainly have. It also doesn't keep or log much detail on articles transferred. .PP Due to a limitation in the Net::NNTP perl module, one of the functions in there Index: doc/man/rnews.1 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/rnews.1,v retrieving revision 1.11 diff -u -r1.11 rnews.1 --- doc/man/rnews.1 2000/08/17 13:30:17 1.11 +++ doc/man/rnews.1 2002/12/03 04:43:09 @@ -84,17 +84,17 @@ .SH OPTIONS .TP .B \-h -If the ``\fB\-h\fP'' flag is given, or failing that, the -environment variable -.I <_ENV_UUCPHOST in include/paths.h> -(typically -.IR UU_MACHINE ) -is set, then +If the ``\fB\-h\fP'' flag is given, then .I rnews will log the Message-ID and host via .IR syslog (3) for each article offered to the server. Logging will only be done if the value is not an empty string. +If ``\fB\-h\fP'' is not set, the environment variable +.I <_ENV_UUCPHOST in include/paths.h> +(typically +.IR $UU_MACHINE ) +will be examined for a similar string. .TP .B \-N Normally, if unpacking the input fails it is re-spooled to @@ -132,7 +132,7 @@ .IR syslog (3). .SH BUGS .I Rnews -cannot process articles that have embedded \e0's in them. +cannot process articles that have embedded ``\e0'' characters in them. .SH HISTORY Written by Rich $alz for InterNetNews. .de R$ Index: doc/man/send-uucp.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/send-uucp.8,v retrieving revision 1.1 diff -u -r1.1 send-uucp.8 --- doc/man/send-uucp.8 1998/06/23 02:33:55 1.1 +++ doc/man/send-uucp.8 2002/12/03 04:43:09 @@ -44,10 +44,10 @@ .PP .I send-uucp compresses batches of news and sends the to the remote site with -.I uux. +.IR uux . .PP .I send-nntp -Starts an innxmit to send the articles to the remote site. +starts an innxmit to send the articles to the remote site. .PP .I send-ihave encapsulates the articles in an @@ -76,18 +76,16 @@ .IR /.log . .SH NOTES You should probably not use send-nntp, but -.I innfeed, +.IR innfeed , or if that is not possible, -.I nntpsend. +.IR nntpsend . .PP The usual flags in the .I newsfeed file to write a batch file suitable for processing by -send-uucp are -.B Tf,Wfb . +send-uucp are ``\fBTf,Wfb\fP''. .PP -The usual flags for a batch file for send-nntp are -.B Tf,Wfm +The usual flags for a batch file for send-nntp are ``\fBTf,Wfm\fP''. .SH "SEE ALSO" newsfeeds(5), nntpsend(8) Index: doc/man/shrinkfile.1 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/shrinkfile.1,v retrieving revision 1.4 diff -u -r1.4 shrinkfile.1 --- doc/man/shrinkfile.1 2000/08/17 13:30:17 1.4 +++ doc/man/shrinkfile.1 2002/12/03 04:43:09 @@ -24,9 +24,9 @@ .I size if the size is larger than .IR maxsize , - preserving the data at the end of the file. +preserving the data at the end of the file. Truncation is performed on line boundaries, where a line is a series -of bytes ending with a newline, \en. +of bytes ending with a newline, ``\en''. There is no line length restriction and files may contain any binary data. .PP Temporary files are created in the @@ -42,7 +42,7 @@ .B \-s By default, .I size -is assume to be zero and files are truncated to zero bytes. +is assumed to be zero and files are truncated to zero bytes. By default, .I maxsize is the same as Index: doc/man/simpleftp.1 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/simpleftp.1,v retrieving revision 1.1 diff -u -r1.1 simpleftp.1 --- doc/man/simpleftp.1 1998/10/28 16:05:56 1.1 +++ doc/man/simpleftp.1 2002/12/03 04:43:09 @@ -14,7 +14,7 @@ batch oriented fashion. It takes one or more ftp URLS on the command line. The file(s) will be retrieved from the remote server and placed in the current directory with the same basename as on the remote; -i.e., ftp://ftp.isc.org/pub/usenet/CONFIG/active.gz is stored as +e.g., ftp://ftp.isc.org/pub/usenet/CONFIG/active.gz is stored as active.gz in the current directory. .SH BUGS .B simpleftp Index: doc/man/sm.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/sm.8,v retrieving revision 1.8 diff -u -r1.8 sm.8 --- doc/man/sm.8 2001/04/23 03:26:56 1.8 +++ doc/man/sm.8 2002/12/03 04:43:09 @@ -28,12 +28,12 @@ program provides a command line interface to the storage manager. If no options are specified, .I sm -shows the whole article associated with the token. +by default shows the entire article associated with the token. The .I token -is a token of the article, and it is stored as the third field of history line. -Standard input is used to read tokens, unless token is given. Each token is -listed in each line in the case. +is a token of the article, as is stored as the third field of history line. +Tokens can be given on the commandline; if none are, they are read from +standard input, one per line. .SH OPTIONS .TP .B \-d \-r @@ -42,7 +42,7 @@ .TP .B \-i If the ``\fB\-i\fP'' flag is used, -then the program shows the newsgroup name and article number +then the program shows only the newsgroup name and article number associated with the token. .TP .B \-q Index: doc/man/startinnfeed.1 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/startinnfeed.1,v retrieving revision 1.2 diff -u -r1.2 startinnfeed.1 --- doc/man/startinnfeed.1 2001/06/16 14:33:39 1.2 +++ doc/man/startinnfeed.1 2002/12/03 04:43:09 @@ -19,7 +19,7 @@ .B imapfeed will be executed (instead of innfeed(8)) with the remaining argument as options. -.SH AUTHOR -James Brister +.SH HISTORY +Written by James Brister. .SH "SEE ALSO" .BR innfeed (8) Index: doc/man/storage.conf.5 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/storage.conf.5,v retrieving revision 1.11 diff -u -r1.11 storage.conf.5 --- doc/man/storage.conf.5 2002/08/10 18:51:32 1.11 +++ doc/man/storage.conf.5 2002/12/03 04:43:10 @@ -5,26 +5,27 @@ .SH DESCRIPTION The storage manager is a unified interface between INN and a variety of different storage method, -allowing the news administrator to choose between different storage method +allowing the news administrator to choose between different storage methods with different tradeoffs (or even use several at the same time for -different newsgroups or articles of different sizes). The rest of INN +different newsgroups, or articles of different sizes). The rest of INN need not care what type of storage method was used for a given article; the storage manager will figure this out automatically when that article is retrieved via the storage API. .PP +The .I /storage.conf file contains the rules to be used in assigning articles to different storage methods. .PP The file consists of a series of storage method entries. Blank lines and lines beginning with a number sign (``#'') are ignored. -The maximum number of character in each line is 255. -The order of entries in this file is important. +The maximum number of characters in each line is 255. +The order of entries in this file is important, see below. .PP Each entry specifies a storage method and a set of rules. Articles that match all of the rules of a storage method entry will be stored using that -storage method. If an article matches multiple storage method entries, -the first one will be used. Each entry is formatted as follows: +storage method; if an article matches multiple storage method entries, +the first will be used. Each entry is formatted as follows: .RS .nf @@ -55,9 +56,8 @@ .B class An identifier for this storage method entry. should be a number and should be unique across all of the entries in this file. It's -used mainly by -.IR expire.ctl (5) -for specifying expiration times by storage class. +used mainly for specifying expiration times by storage class as described in +.IR expire.ctl (5). .TP .B newsgroups What newsgroups are stored using this storage method. is a @@ -65,7 +65,9 @@ pattern that is matched against the newsgroups an article is posted to. If ``storeonxref'' in inn.conf is ``true'', this pattern will be matched against the newsgroup names in the ``Xref'' header; otherwise, it will be -matched against newsgroup names in the ``Newsgroups'' header. Poison +matched against newsgroup names in the ``Newsgroups'' header (see +.IR inn.conf (5) +for discussion of the differences between these possibilities). Poison wildmat expressions (expressions starting with ``@'') are allowed and can be used to exclude certain group patterns. ``!'' cannot be used, however. The pattern is matched in order. There is no default newsgroups @@ -77,7 +79,7 @@ storage method. If is ``0'' or not given, the upper size of articles is limited only by ``maxartsize'' in -.IR inn.conf (5). +.IR inn.conf . The ``size'' field is optional and may be omitted entirely if you want articles of any size (that otherwise fulfill the requirements of this storage method entry) to be stored in this storage method. @@ -89,13 +91,16 @@ .B only on the ``Expires'' header of the article, not on any local expiration policies or anything in -.IR expire.ctl (5)! -If is non-zero, then this entry will not match any article -without an ``Expires'' header. This key is therefore only really useful -for assigning articles with requested longer expire times to a separate -storage method. and are boundaries on the amount of -time into the future the ``Expires'' header of the article requests that -it remain around, and are formatted 0d0h0m0s (days, hours, minutes, and +.IR expire.ctl ! +If is non-zero, then this entry +.B will not match +any article without an ``Expires'' header. +This key is therefore only really useful for assigning articles with +requested longer expire times to a separate storage method. Articles only +match if the time until expiration (that is, the amount of time into the +future that the ``Expires'' header of the article requests that it remain +around) falls in the interval specified by and . The +format of these parameters is 0d0h0m0s (days, hours, minutes, and seconds into the future). If is ``0s'' or is not specified, there is no upper bound on expire times falling into this entry (note that this key has no effect on when the article will actually be expired, only @@ -112,7 +117,9 @@ .TP .B exactmatch If this key is set to ``true'', all newsgroups will be examined to see if -they match newsgroups patterns. This is a boolan value and ``true'', ``yes'' +they match newsgroups patterns. (Normally, any nonzero number of matching +newsgroups is sufficient, provided no newsgroup matches a poison wildmat as +described above.) This is a boolan value and ``true'', ``yes'' and ``on'' are usable to enable this key. The case of these values is not significant. The default is false. .PP @@ -140,10 +147,10 @@ method entry. .SH STORAGE METHODS Currently, there are four storage methods available. Each method has its -characteristics. You can choose any of them to be suitable for your +pros and cons; you can choose any mixture of them as is suitable for your environment. Note that each method has an attribute ``EXPENSIVESTAT'' which -means whether checking existense of article is expensive or not. This is used -to run +indicates whether checking the existence of an article is expensive or not. +This is used to run .IR expireover (8). .TP .B cnfs @@ -155,14 +162,15 @@ around to the beginning and stores new articles over top of the oldest articles in the buffer. The expire time of articles stored in CNFS buffers is therefore entirely determined by how long it takes the buffer -to wrap around, which depends on how much data is being stored in it. +to wrap around, which depends on how quickly data is being stored in it. (This method is therefore said to have self-expire functionality.) \&``EXPENSIVESTAT'' is ``FALSE'' for this method. CNFS has its own configuration file, -.IR cycbuff.conf (5). +.IR cycbuff.conf , +which describes some subtlties to the basic description given above. Storage method entries for the ``cnfs'' storage method must have an -\&``options'' field specifying the metacycbuff into which articles matching -that entry should be stored. See +\&``options'' field specifying the metacycbuff into which articles +matching that entry should be stored; see .IR cycbuff.conf (5) for details on metacycbuffs. .TP @@ -170,11 +178,12 @@ This method stores multiple articles in one file, whose name is based on the article's arrival time and the storage class. The file name will be .IR /timecaf-nn/bb/aacc.CF , -where ``nn'' is the hexadecimal value of and ``bb'' and -\&``aacc'' are hexadecimal components of the arrival time. (The arrival -time in seconds since epoch is converted to hex and interpreted as -0xaabbccFF, with ``aa'', ``bb'', and ``cc'' used to build the path.) This -method does not have self-expire functionality (meaning +where ``nn'' is the hexadecimal value of , ``bb'' and +\&``aacc'' are hexadecimal components of the arrival time, and ``CF'' is a +hardcoded extension. (The arrival time, in seconds since the epoch, is +converted to hexadecimal and interpreted as 0xaabbccdd, with ``aa'', +``bb'', and ``cc'' used to build the path.) This method does not have +self-expire functionality (meaning .IR expire (8) has to run periodically to delete old articles). \&``EXPENSIVESTAT'' is ``FALSE'' for this method. @@ -187,7 +196,7 @@ where ``nn'' is the hexadecimal value of , ``yyyy'' is a hexadecimal sequence number, and ``bb'', ``cc'', and ``aadd'' are components of the arrival time in hexadecimal (the arrival time is -converted to hex and interpreted as 0xaabbccdd). This method does not +interpreted as documented above under ``timecaf''). This method does not have self-expire functionality. \&``EXPENSIVESTAT'' is ``TRUE'' for this method. .TP @@ -199,7 +208,7 @@ article was posted with each period changed to a slash, and ``nnnnn'' is the sequence number of the article in that newsgroup. For crossposted articles, the article is linked into each newsgroup to which it is -crossposted (using either hard or symbolic links). This is the way all +crossposted (using either hard or symbolic links). This is the way versions of INN prior to 2.0 stored all articles, as well as being the article storage format used by C News and earlier news systems. This method does not have self-expire functionality. @@ -215,9 +224,9 @@ .SH EXAMPLE The following sample storage.conf file would store all articles posted to alt.binaries.* in the ``BINARIES'' CNFS metacycbuff, all articles over -roughly 50KB in any other hierarchy in the ``LARGE'' CNFS metacycbuff, all -other articles in alt.* in one timehash class, and all other articles in -any newsgroups in a second timehash class, except for the internal.* +roughly 50 KB in any other hierarchy in the ``LARGE'' CNFS metacycbuff, +all other articles in alt.* in one timehash class, and all other articles +in any newsgroups in a second timehash class, except for the internal.* hierarchy which is stored in traditional spool format. .RS .nf @@ -256,7 +265,7 @@ a good habit to get into; make sure that you have at least one catch-all entry just in case something you didn't expect falls through the cracks. Notice also that the special rule for the internal.* hierarchy is first, -so it will catch even articles crossposted to alt.binaries.* or over 50KB +so it will catch even articles crossposted to alt.binaries.* or over 50 KB in size. .SH HISTORY Written by Katsuhiro Kondou for InterNetNews. Index: doc/man/tally.control.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/tally.control.8,v retrieving revision 1.3 diff -u -r1.3 tally.control.8 --- doc/man/tally.control.8 1998/04/09 15:16:17 1.3 +++ doc/man/tally.control.8 2002/12/03 04:43:10 @@ -1,6 +1,6 @@ .TH TALLY.CONTROL 8 .SH NAME -tally.control \- keep track of newgroup creation and deletions. +tally.control \- keep track of newsgroup creations and deletions. .SH SYNOPSIS tally.control .SH DECSRIPTION @@ -22,6 +22,7 @@ .. .R$ $Id: tally.control.8,v 1.3 1998/04/09 15:16:17 mibsoft Exp $ .SH "SEE ALSO" +newslog(5), news.daily(8), scanlogs(8), tally.unwanted(8), Index: doc/man/writelog.8 =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/man/writelog.8,v retrieving revision 1.4 diff -u -r1.4 writelog.8 --- doc/man/writelog.8 1998/12/09 15:53:55 1.4 +++ doc/man/writelog.8 2002/12/03 04:43:10 @@ -3,8 +3,8 @@ writelog \- add a entry to an INN log file. .SH SYNOPSIS .B writelog -.B name -.B text... +.I name +.I text... .SH DESCRIPTION .PP The Index: doc/pod/checklist.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/checklist.pod,v retrieving revision 1.2 diff -u -r1.2 checklist.pod --- doc/pod/checklist.pod 2002/03/02 20:49:20 1.2 +++ doc/pod/checklist.pod 2002/12/03 04:43:10 @@ -23,7 +23,7 @@ You want to be careful that things in that directory stay owned by "news" -- but you can't just C after the install, because you may have binaries that are SUID root. You can do the build -as any users, because C will set the permissions +as any user, because C will set the permissions correctly. After that point, though, you may want to C to avoid creating any files as root. (For routine maintenance once INN is working, you can generally be root.) @@ -69,9 +69,9 @@ =item * Work out configure options (C<./configure --help> for a list). If you -aren't working out F, or want to put some files on a +aren't working out of F, or want to put some files on a different partition, you can set the directories now (or later in -F if you change your mind.) +F if you change your mind). You probably want C<--with-perl>. If you're not using NetBSD with cycbuffs or OpenBSD, perhaps C<--with-tagged-hash>. You might want to Index: doc/pod/ckpasswd.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/ckpasswd.pod,v retrieving revision 1.5 diff -u -r1.5 ckpasswd.pod --- doc/pod/ckpasswd.pod 2002/08/27 05:01:19 1.5 +++ doc/pod/ckpasswd.pod 2002/12/03 04:43:11 @@ -10,7 +10,7 @@ =head1 DESCRIPTION B is the basic password authenticator for nnrpd, suitable for -being run from an auth stanza in readers.conf(5). See readers.conf(5) for +being run from an auth stanza in I. See readers.conf(5) for more information on how to configure an nnrpd authenticator. B accepts a username and password from nnrpd and tells nnrpd(8) @@ -86,7 +86,7 @@ =item B<-g> Attempt to look up system group corresponding to username and return a -string like "user@group" to be matched against in readers.conf(5). This +string like "user@group" to be matched against in F. This option is incompatible with the B<-d> and B<-f> options. =item B<-p> I @@ -112,12 +112,9 @@ specifically audited for such uses! It is, however, a very small program that you should be able to check by hand for security. -This configuration is not recommended if it can be avoided, since the NNTP -protocol has no way of protecting passwords from casual interception, and -using system passwords to authenticate NNTP connections therefore opens -you up to the risk of password sniffing. If you do use system passwords -to authenticate connections, you should seriously consider only doing NNTP -through ssh tunnels or over SSL. +This configuration is not recommended if it can be avoided, for serious +security reasons. See L(5)/SECURITY CONSIDERATIONS> for +discussion. =item B<-u> I Index: doc/pod/control.ctl.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/control.ctl.pod,v retrieving revision 1.1 diff -u -r1.1 control.ctl.pod --- doc/pod/control.ctl.pod 2002/11/26 07:31:29 1.1 +++ doc/pod/control.ctl.pod 2002/12/03 04:43:11 @@ -63,7 +63,7 @@ The action is performed as in B, and additionally a log entry is written to the specified log file I. If I is the word C, the log entry is mailed to the news administrator instead. An -empty string is equivalent to /dev/null and says to log nothing. +empty string is equivalent to F and says to log nothing. If I starts with a slash, it is taken as the absolute filename to use for the log file. Otherwise, the filename is formed by prepending @@ -141,7 +141,7 @@ see pgpverify(8). Control messages of type cancel are handled internally by B and -cannot be controlled by any of the mechanisms described here. +cannot be affected by any of the mechanisms described here. =head1 EXAMPLE Index: doc/pod/expireover.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/expireover.pod,v retrieving revision 1.1 diff -u -r1.1 expireover.pod --- doc/pod/expireover.pod 2001/01/09 09:17:26 1.1 +++ doc/pod/expireover.pod 2002/12/03 04:43:12 @@ -15,9 +15,9 @@ from the overview database mentions of any articles that no longer exist in the news spool. -If I in inn.conf(5) is true, B also removes +If I in I is true, B also removes old articles from the news spool according to the expiration rules in -expire.ctl(5). Otherwise it only removes overview entries for articles +F. Otherwise it only removes overview entries for articles that have already been removed by some other process, and B<-e>, B<-k>, B<-N>, B<-p>, B<-q>, B<-w>, and B<-z> are all ignored. @@ -28,12 +28,12 @@ that individual newsgroup. The effect is that an article crossposted to several groups will be removed from the overview database from each group one-by-one as its age passes the expiration threshold for that group as -set in expire.ctl(5), and then when it expires out of the last newsgroup, +set in F, and then when it expires out of the last newsgroup, it will be deleted from the news spool. Articles that are stored in self-expiring storage backends such as CNFS are normally treated differently and not expired until they expire out of -the backend regardless of expire.ctl(5). See B<-N>, however. +the backend regardless of F. See B<-N>, however. By default, B purges all overview information for newsgroups that have been removed from the server; this behavior is suppressed if @@ -63,15 +63,15 @@ Retain all overview information for an article, as well as the article itself, until it expires out of all newsgroups to which it was posted. This can cause articles to stick around in a newsgroup for longer than the -expire.ctl(5) rules say when they're crossposted. B<-e> and B<-k> cannot -be used at the same time. This flag is ignored if I is -false. +F rules indicate, when they're crossposted. B<-e> and B<-k> +cannot be used at the same time. This flag is ignored if +I is false. =item B<-N> -Apply control.ctl(5) rules to expire articles even from storage methods +Apply F rules to expire articles even from storage methods that have self-expire functionality. This may remove articles from -self-expiring storage methods before the articles expire "naturally." +self-expiring storage methods before the articles "naturally" expire. This flag is ignored if I is false. =item B<-p> @@ -101,7 +101,7 @@ "Warps" time so that B thinks that it's running at some time other than the current time. This is occasionally useful to force groups -to be expired or not expired without changing expire.ctl(5) for the expire +to be expired or not expired without changing F for the expire run. I should be a signed floating point number specifying the number of days difference from the current time to use as "now." This flag is ignored if I is false. @@ -128,8 +128,8 @@ Normally B is invoked from news.daily(8), which handles such things as processing the I and I if necessary. -Sometimes it's convenient to expire a particular newsgroup, however. This -can be done with a command like: +Sometimes it's convenient to manually expire a particular newsgroup, +however. This can be done with a command like: echo example.test | expireover -f - -Z /usr/local/news/tmp/lowmark ctlinnd lowmark /usr/local/news/tmp/lowmark Index: doc/pod/fastrm.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/fastrm.pod,v retrieving revision 1.1 diff -u -r1.1 fastrm.pod --- doc/pod/fastrm.pod 2001/01/04 05:57:21 1.1 +++ doc/pod/fastrm.pod 2002/12/03 04:43:12 @@ -44,8 +44,8 @@ Various additional optimizations for removing files can be turned on and/or tuned with options (see below). Which options will be most effective depends heavily on the underlying structure of the file system, -the way in which directories are stored and searched, and similar often -underdocumented operating system implementation details. The more +the way in which directories are stored and searched, and similar, often +underdocumented, operating system implementation details. The more sophisticated the underlying operating system and file system, the more likely that it will already perform the equivalent of these optimizations internally. Index: doc/pod/hacking.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/hacking.pod,v retrieving revision 1.20 diff -u -r1.20 hacking.pod --- doc/pod/hacking.pod 2002/09/26 22:46:04 1.20 +++ doc/pod/hacking.pod 2002/12/03 04:43:14 @@ -219,22 +219,22 @@ The test suite for INN is located in the tests directory and is just getting started. The test suite consists of a set of programs listed in -tests/TESTS and the scaffolding in the runtests program. +F and the scaffolding in the F program. Adding new tests is very straightforward and very flexible. Just write a program that tests some part of INN, put it in a directory under tests named after the part of INN it's testing (all the tests so far are in lib because they're testing libinn routines), and have it output first a line -containing the count of test cases in that file and then for each test a +containing the count of test cases in that file, and then for each test a line saying "ok n" or "not ok n" where n is the test case number. (If a test is skipped for some reason, such as a test of an optional feature -that wasn't compiled into INN, the test program should output S<" # skip"> -on the same line after "ok n".) Add any rules necessary to build the test -to tests/Makefile (note that for simplicity it doesn't recurse into -subdirectories) and make sure it creates an executable ending in .t. Then -add the name of the test to tests/TESTS, without the .t ending. +that wasn't compiled into INN, the test program should output +S<"ok n # skip">.) Add any rules necessary to build the test to +tests/Makefile (note that for simplicity it doesn't recurse into +subdirectories) and make sure it creates an executable ending in F<.t>. +Then add the name of the test to tests/TESTS, without the .t ending. -One naming convention: To distinguish more easily between e.g. +One naming convention: to distinguish more easily between e.g. lib/error.c (the implementation) and tests/lib/error-t.c (the test suite), we add -t to the end of the test file names. So tests/lib/error-t.c is the source that compiles into an executable tests/lib/error.t which is run @@ -527,7 +527,7 @@ if (p != NULL) return p; -This is in part for a practical reason: Some code coverage analysis tools +This is in part for a practical reason: some code coverage analysis tools like purecov will count the second example above as a single line and won't notice if the condition always evaluates the same way. @@ -672,13 +672,13 @@ =item 5. Check out a copy of the release branch. It's currently necessary to run -configure to generate Makefile.global. Then run make check-manifest. The -only differences should be files that are generated by configure; if there -are any other differences, fix the MANIFEST. +configure to generate Makefile.global. Then run C. +The only differences should be files that are generated by configure; if +there are any other differences, fix the MANIFEST. =item 6. -Run make release. Note that you need to have a copy of cvs2cl from +Run C. Note that you need to have a copy of cvs2cl from to do this. You will be prompted for the release branch tag, the date from which to generate the ChangeLog, and the path to cvs2cl. Start the ChangeLog slightly before the last release Index: doc/pod/hook-perl.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/hook-perl.pod,v retrieving revision 1.6 diff -u -r1.6 hook-perl.pod --- doc/pod/hook-perl.pod 2002/11/23 07:29:57 1.6 +++ doc/pod/hook-perl.pod 2002/12/03 04:43:16 @@ -16,6 +16,8 @@ the article, and can optionally do other, more complicated processing (such as add history entries, cancel articles, spool local posts into a holding area, or even modify the headers of locally submitted posts). +The Perl authentication hooks allow you to replace or supplement the +readers.conf mechanism used by nnrpd. For Perl filtering support, you need to have Perl version 5.004 or newer. Earlier versions of Perl will fail with a link error at compilation time. @@ -36,7 +38,7 @@ filter code can be specified at configure time by giving the flag B<--with-filter-dir> to configure. -INN doesn't care what Perl functions you define in what files. The only +INN doesn't care what Perl functions you define in which files. The only thing that's different about the two files is when they're loaded. F is loaded only once, when innd first starts, and is never reloaded as long as innd is running. Any modifications to that file @@ -174,7 +176,7 @@ can be reloaded when innd restarts (possibly by F). The state of the Perl interpretor in which all of these Perl functions run -is preserved over the lifetime of innd. In other words, it's allowed for +is preserved over the lifetime of innd. In other words, it's permissible for the Perl code to create its own global Perl variables, data structures, saved state, and the like, and all of that will be available to filter_art() and filter_messageid() each time they're called. The only @@ -184,7 +186,7 @@ Perl filtering can be turned off with C and back on again with C. Perl filtering is turned off automatically if loading of the filter fails or if the filter code returns any sort of a -fatal error (either due to Perl itself or due to a die in the Perl code). +fatal error (either due to Perl itself or due to a C in the Perl code). =head1 Supported innd Callbacks @@ -198,11 +200,12 @@ Adds I to the history database. All of the arguments except the first one are optional; the times default to the current time and the paths field defaults to the empty string. (For those unfamiliar with the -fields of a history database entry, the I is normally the time at +fields of a history(5) database entry, the I is normally the time at which the server accepts the article, the I is from the Date header of the article, the I is from the Expires header of the -article, and the I field is the storage API token.) Returns true -on success, false otherwise. +article, and the I field is the storage API token. All three times +as measured as a time_t since the epoch.) Returns true on success, false +otherwise. =item INN::article(I) @@ -273,7 +276,7 @@ =head1 The nnrpd Posting Filter -Whenever perl support is needed in nnrpd, it first loads the file +Whenever Perl support is needed in nnrpd, it first loads the file _PATH_PERL_FILTER_NNRPD (defined in F, by default F). This file must be located in the directory specified by pathfilter in F (F @@ -284,7 +287,7 @@ If F loads successfully and defines the Perl function filter_post(), Perl filtering is turned on. Otherwise, it's turned off. If filter_post() ever returns a fatal error (either from Perl or from a -die in the Perl code), Perl filtering is turned off for the life of that +C in the Perl code), Perl filtering is turned off for the life of that nnrpd process and any further posts made during that session won't go through the filter. @@ -300,7 +303,7 @@ headers of the article. (Unlike the innd Perl filter, %hdr for the nnrpd Perl filter contains *all* of the headers, not just the standard ones. If any of the headers are duplicated, though, %hdr will contain only the -value of the second occurance of the header. nnrpd will reject the +value of the last occurance of the header. nnrpd will reject the article before the filter runs if any of the standard headers are duplicated.) It also has access to the full body of the article in the variable $body, and if the poster authenticated via AUTHINFO (or if either @@ -346,14 +349,15 @@ The remainder of this section is an introduction to the new mechanism (which uses the perl_auth: and perl_access: F parameters) -for people familiar with the old mechanism (identifiable by the -nnrpperlauth: parameter in F). Other people should skip this -section. - -The perl_auth parameter allows the use of perl to authenticate a user. -It works in the same manner as the auth parameter (part of -readers.conf): +with porting/migration suggestions for people familiar with the old +mechanism (identifiable by the nnrpperlauth: parameter in F). +Other people should skip this section. + +The perl_auth parameter allows the use of Perl to authenticate a user. +Scripts (like those from the old mechanism) are listed in F +using perl_auth in the same manner other authenticators are using auth: + perl_auth: "/path/to/script/auth1.pl" The file given as argument to perl_auth should contain the same @@ -372,41 +376,40 @@ The perl_access parameter (described below) is also new; it allows the dynamic generation of an access group for an incoming connection using -a perl script. If a connection matches an auth group with a -perl_access parameter, all access groups in readers.conf are ignored -and the procedure described below is used to generate an access group. +a Perl script. If a connection matches an auth group which has a +perl_access parameter, all access groups in readers.conf are ignored; +instead the procedure described below is used to generate an access group. This concept is due to Jeffrey M. Vinocur. The new functionality should provide all of the existing capabilities -of the perl hook, in combination with the flexibility of readers.conf +of the Perl hook, in combination with the flexibility of readers.conf and the use of other authentication and resolving programs. To use an -perl authentication code that predates the readers.conf mechanism, you +Perl authentication code that predates the readers.conf mechanism, you would need to modify the code slightly (see below for the new specification) and supply a simple readers.conf file. If you don't want to modify your code, the samples directory has F and F which should allow you to use your old code without needing to change it. -However, before trying to use your old perl code, you may want to -consider replacing it entirely with non-perl authentication. (With +However, before trying to use your old Perl code, you may want to +consider replacing it entirely with non-Perl authentication. (With readers.conf and the regular authenticator and resolver programs, much -of what once required perl can be done directly.) Even if the -functionality is not available directly, you may prefer writing a new +of what once required Perl can be done directly.) Even if the +functionality is not available directly, you may wish to write a new authenticator or resolver (which can be done in whatever language you -prefer) to working in perl. +prefer) to working in Perl. =head1 Perl Authentication Support for nnrpd -Support for authentication via perl is provided in nnrpd by the +Support for authentication via Perl is provided in nnrpd by the inclusion of a perl_auth: parameter in a F auth group. perl_auth: works exactly like the auth: parameter in -F, the only difference is that it calls the script given -as argument using the perl hook rather then treating it as an external -program. +F, except that it calls the script given as argument using +the Perl hook rather then treating it as an external program. If the processing of readers.conf requires that a perl_auth: statement -be used for authentication, perl is loaded (if it has yet to be) and +be used for authentication, Perl is loaded (if it has yet to be) and the file given as argument to the perl_auth: parameter is loaded as well. If a Perl function auth_init() is defined by that file, it is called immediately after the file is loaded. It takes no arguments and returns @@ -448,12 +451,12 @@ =head1 Dynamic Generation of Access Groups -A perl script may be used to dynamically generate an access group +A Perl script may be used to dynamically generate an access group which is then used to determine the access rights of the client. This occurs whenever the perl_access: is specified in an auth group which has successfully matched the client. -When a perl_access: parameter is encountered, perl is loaded (if it +When a perl_access: parameter is encountered, Perl is loaded (if it has yet to be) and the file given as argument is loaded as well. Provided the file loads without errors, and a Perl function access() is defined, access() will then be called. access() takes @@ -466,17 +469,29 @@ C<$attributes{username}> will contain the provided username and domain (in username@domain form). -access() returns a hash, containing the desired access parameters and -values. Here is a trivial example: +access() returns a hash, containing the desired access parameters and +values. Here is an untested example showing how to dynamically generate a +list of newsgroups based on the client's username and domain. + my %hosts = ( "example.com" => "example.*", "isc.org" => "isc.*" ); + sub access { - %return_hash = ( - "read" => "*", - "post" => "local.*", - "virtualhost" => "true", + %return_hash = ( + "max_rate" => "10000", + "addnntppostinghost" => "true", # ... - ); - return %return_hash; + ); + if( defined $attributes{username} && + $attributes{username} =~ /.*@(.*)/ ) + { + $return_hash{"virtualhost"} = "true"; + $return_hash{"path"} = $1; + $return_hash{"newsgroups"} = $hosts{$1}; + } else { + $return_hash{"read"} = "*"; + $return_hash{"post"} = "local.*" + } + return %return_hash; } Note that both the keys and values are quoted strings. These values @@ -487,7 +502,7 @@ While you may include the users: parameter in a dynamically generated access group, some care should be taken (unless your pattern is just * which is equivalent to leaving the parameter out). The group created -with the values returned from the perl script is the only one +with the values returned from the Perl script is the only one considered when nnrpd attempts to find an access group matching the connection. If a users: parameter is included and it doesn't match the connection, then the client will be denied access since there are no Index: doc/pod/hook-python.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/hook-python.pod,v retrieving revision 1.1 diff -u -r1.1 hook-python.pod --- doc/pod/hook-python.pod 2000/11/07 12:53:11 1.1 +++ doc/pod/hook-python.pod 2002/12/03 04:43:17 @@ -263,11 +263,11 @@ =head1 PYTHON AUTHENTICATION AND AUTHORIZATION SUPPORT FOR NNRPD Python authentication and authorization support in nnrpd along with -filtering support in innd may be compiled in by giving C<--with-python> -command line flag to configure script. Python authentication and -authorization may be turned on by nnrppythonauth setting in F. +filtering support in innd may be compiled in by passing C<--with-python> +C. Python authentication and authorization may be enabled with +the nnrppythonauth setting in F. -If nnrppythonauth is set to true in F, nnrpd will load the +If nnrppythonauth in F is set to true, nnrpd will load the Python module defined in include/paths.h and located in the directory specified by pathfilter in F. Once that module is loaded, nnrpd will authenticate and authorize readers by calling a Python methods rather Index: doc/pod/inn.conf.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/inn.conf.pod,v retrieving revision 1.37 diff -u -r1.37 inn.conf.pod --- doc/pod/inn.conf.pod 2002/09/09 00:25:30 1.37 +++ doc/pod/inn.conf.pod 2002/12/03 04:43:20 @@ -23,7 +23,7 @@ : (Any amount of whitespace can be put after the colon and is optional.) If -the value contains embedded whitespace or any of the characers C<[]<>"\>, +the value contains embedded whitespace or any of the characers C<[]<>"\:>, it must be enclosed in double quotes (""). A backslash (C<\>) can be used to escape quotes and backslashes inside double quotes. is case-sensitive; C is not the same as C or C. @@ -44,7 +44,8 @@ rather than as a tutorial. If this is your first exposure to INN and these parameters, it would be better to start by reading other man pages and referring to this one only when an F parameter is explicitly -mentioned. +mentioned. Those parameters which need to be changed when setting up a +new server are discussed in F. =head1 PARAMETERS @@ -62,8 +63,10 @@ if the GetFQDN() routine in libinn(3) cannot get the fully-qualified domain name by using either the gethostname(3) or gethostbyname(3) calls. The check is very simple; if either routine returns a name with a period -in it, then it is assumed to have the full domain name. The default value -is unset. +in it, then it is assumed to have the full domain name. As this parameter +is rarely used, do not use it to affect the righthand side of +autogenerated Message-IDs; see instead I in L. +The default value is unset. =item I @@ -142,9 +145,10 @@ Like I but for IPv6 sockets. If only one of the I and I parameters is used, then only the socket for the corresponding address family is created. If both parameters are used -then two sockets are created. If none of them is used, the list of +then two sockets are created. If neither of them is used, the list of sockets to listen on will be determined by the system library -I function. +I function. The value of the INND_BIND_ADDRESS6, if set, +overrides this setting. The default value is unset. =item I @@ -193,7 +197,7 @@ The maximum size of article (headers and body) that will be accepted by the server, in bytes. A value of C<0> allows any size of article. The -default value is C<1000000> (approximately 1MB). See also +default value is C<1000000> (approximately 1 MB). See also I. =item I @@ -213,7 +217,7 @@ Whether to enable PGP verification of control messages other than cancel. This is a boolean value and the default is based on whether configure found -pgp or pgpv. +pgp, pgpv, or gpgv. =item I @@ -253,10 +257,11 @@ =item I Which local IP address to bind to for outgoing NNTP sockets (used by -innxmit(8) among other programs). This must be in dotted-quad format -(nnn.nnn.nnn.nnn). If set to C or not set, the operating system will -choose the source IP address for outgoing connections. The default value -is unset. +innxmit(8) among other programs, but I innfeed(8) -- see +I in innfeed.conf(5) for that). This must be in dotted-quad +format (nnn.nnn.nnn.nnn). If set to C or not set, the operating +system will choose the source IP address for outgoing connections. The +default value is unset. =item I @@ -296,10 +301,12 @@ =item I -Normally innd(8) rejects article, if article filter (PERL, Python and TCL) -is enabled and it tells innd to reject it. It's never rejected if this is -set to true. This is useful when C is specified in newsfeeds(5) not -to feed it for the site. +Normally innd(8) rejects incoming articles when directed to do so by any +enabled article filters (Perl, Python, and TCL). However, this parameter +causes such articles I to be rejected; instead filtering can be +applied on outbound articles. If this parameter is set, all articles will +be accepted on the local machine, but articles rejected by the filter will +I be fed to any peers specified in F with the C flag. =back @@ -330,15 +337,16 @@ Whether to enable newsgroup-based expiry. If set to false, article expiry is done based on storage class of storing method. If set to true (and overview information is available), expiry is done by newsgroup name. -This effects the format of F. This is a boolean value and the +This affects the format of F. This is a boolean value and the default is true. =item I Whether to file all postings to C groups in the pseudonewsgroup C. If this is set to true, the newsgroup C must exist in the -F file or INN will not start. This is a boolean value and the -default is false. +F file or INN will not start. (See the discussion of C +groups in innd(8) under CONTROL MESSAGES.) This is a boolean value and +the default is false. =item I @@ -401,10 +409,10 @@ =item C -Stores history data in the INN history v6 format - history(5) text -file and a number of dbz database files; this may be in true history -v6 format, or tagged hash format depending on the build -options. Separation of these two is a project which has not yet been +Stores history data in the INN history v6 format: history(5) text +file and a number of dbz(3) database files; this may be in true history +v6 format, or tagged hash format, depending on the build +options. Separation of these two is a project which has not yet been undertaken. =back @@ -421,17 +429,18 @@ =item I -Whether to create overview data innd(8) internally through libstorage(3). -If set to false, innd create overview data by itself. If set to true, -innd does not create. In the case, you need to run overchan(8) by -creating entry in newsfeeds(5). Setting to true may be useful, if innd -can not keep up with incoming feed and the bottle neck is creating overview -data within innd. This is a boolean value and the default is false. +Whether to innd(8) should create overview data internally through +libstorage(3). If set to false, innd creates overview data by itself. If +set to true, innd does not create; instead overview data must be created +by overchan(8) from an appropriate entry in F. Setting to true +may be useful, if innd cannot keep up with incoming feed and the +bottleneck is creation of overview data within innd. This is a boolean +value and the default is false. =item I Only used with the tradspool storage method, this says whether to write -articles in wire format. Wire format means storing articles with \r\n at +articles in wire format. Wire format means storing articles with C<\r\n> at the end of each line and with periods at the beginning of lines doubled, the article format required by the NNTP protocol. Articles stored in this format are suitable for sending directly to a network connection without @@ -453,7 +462,9 @@ example) and see the same internal article numbering. Servers with this parameter set should generally only have one upstream feed, and should always have I set to hand locally posted articles off to -the master server. This is a boolean value and the default is false. +the master server. The upstream should be careful to always feed articles +in order (innfeed(8) can have problems with this in the event of a +backlog). This is a boolean value and the default is false. =item I @@ -498,7 +509,7 @@ to put a heavy load on the server in older versions of INN, but is now reasonably efficient, at least if only one newsgroup is specified by the client. This is a boolean value and the default is true. If you use the -I parameter in readers.conf(5), be sure to read about the way it +I parameter in F, be sure to read about the way it overrides I. =item I @@ -529,6 +540,11 @@ number of "article is missing" errors seen by the client. This is a boolean value and the default is true. +=item I + +This parameter is now obsolete; see "Changes to Perl Authentication +Support for nnrpd" in F. + =item I Whether to use the Python hook in nnrpd(8) to authenticate readers. If @@ -542,9 +558,8 @@ connections from hosts not listed in F. If this parameter is set to true, those connections will instead be rejected with a 502 error code. This should be set to true for a transit-only server that -doesn't support readers, if nnrpd is being started out of inetd, or if -nnrpd is run in daemon mode. This is a boolean value and the default is -false. +doesn't support readers, or if nnrpd is running in daemon mode or being +started out of inetd. This is a boolean value and the default is false. =item I @@ -556,12 +571,11 @@ =item I Whether to enable the tracking system for client behavior. Tracked -information is recoreded to I/tracklogs/log-ID. ID is determined -by nnrpd's PID and when nnrpd runs. Currenlty that information includes -the messages which tell enabling reader track and where posted article is -tracked. Which user and client, that is recorded, is determined by -nnrpd.track. See nnrpd.track(5) for more information. This is a boolean -value and the default is false. +information is recorded to I/tracklogs/log-ID, where ID is +determined by nnrpd's PID and launch time.) Currently the information +recorded includes initial connection and posting; only information about +clients listed in F is recorded. This is a boolean value and +the default is false. =item I @@ -596,12 +610,12 @@ Articles larger than this value in bytes will not have keywords generated for them (since it would take too long to do so). The default value is -C<100000> (approximately 100KB). +C<100000> (approximately 100 KB). =item I Maximum number of bytes allocated for keyword data. If there are more -keywords than will fit, separated by commas, into this many bytes, the +keywords than will fit into this many bytes when separated by commas, the rest are discarded. The default value is C<512>. =item I @@ -662,8 +676,9 @@ =item I The maximum article size (in bytes) for locally posted articles. Articles -larger than this will be rejected. Also see I. The default -value is C<1000000> (approximately 1MB). +larger than this will be rejected. See also I, which applies +to all articles including those posted locally. The default value is +C<1000000> (approximately 1 MB). =item I @@ -690,8 +705,9 @@ =item I If set, nnrpd(8) and rnews(1) will pass all locally posted articles to the -specified host rather than trying to inject them locally. This should -always be set if I is true. The default value is unset. +specified host rather than trying to inject them locally. See also +I. This should always be set if I is true. The +default value is unset. =item I @@ -738,7 +754,8 @@ previous sleep time, see below). After a configurable number of posts in a configurable period of time, nnrpd(8) will activate posting backoff and begin to sleep for increasing periods of time before actually posting -anything. Posts will still be accepted, but an increasingly reduced rate. +anything. Posts will still be accepted, but at an increasingly reduced +rate. After backoff has been activated, the length of time to sleep is computed based on the difference in time between the last posting and the current @@ -767,8 +784,8 @@ The path to a directory, writeable by the news user, that will contain the backoff database. There is no default for this parameter; you must -provide a path to an creatable and writeable directory, if exists, to enable -exponential backoff. +provide a path to a creatable or writeable directory to enable exponential +backoff. =item I @@ -786,8 +803,8 @@ Postings from the same identity that arrive in greater than this amount of time (in seconds) will reset the backoff algorithm. Another way to look -at this constant is to realize that posters will be allowed to post -86400/I posts per day. The default value is C<1>. +at this constant is to realize that posters will be allowed to generate at +most 86400/I posts per day. The default value is C<1>. =item I @@ -811,31 +828,34 @@ =item I -Free space in I, in inndf(8) output units, at which innd(8) -will be throttled by innwatch(8), assuming a default innwatch.ctl(5). The -default value is C<800>. +Free space in I, in inndf(8) output units (normally +kilobytes), at which innd(8) will be throttled by innwatch(8), assuming a +default F. The default value is C<800>. =item I -Free space in I, in inndf(8) output units, at which innd(8) will -be throttled by innwatch(8), assuming a default innwatch.ctl(5). The -default value is C<25000>. +Free space in I, in inndf(8) output units (normally kilobytes), at +which innd(8) will be throttled by innwatch(8), assuming a default +F. The default value is C<25000>. =item I -Load average times 100 at innd(8) will be restarted by innwatch(8) +Load average times 100 at which innd(8) will be restarted by innwatch(8) (undoing a previous pause or throttle), assuming a default -innwatch.ctl(5). The default value is C<1000>. +F. The default value is C<1000> (that is, a load average of +10.00). =item I Load average times 100 at which innd(8) will be throttled by innwatch(8), -assuming a default innwatch.ctl(5). The default value is C<2000>. +assuming a default F. The default value is C<2000> (that +is, a load average of 20.00). =item I Load average times 100 at which innd(8) will be paused by innwatch(8), -assuming a default innwatch.ctl(5). The default value is C<1500>. +assuming a default F. The default value is C<1500> (that +is, a load average of 15.00). =item I @@ -845,14 +865,15 @@ =item I Free inodes in I at which innd(8) will be throttled by -innwatch(8), assuming a default innwatch.ctl(5). The default value is +innwatch(8), assuming a default F. The default value is C<200>. =item I Free space in I and I, in inndf(8) output -units, at which innd(8) will be throttled by innwatch(8), assuming a -default innwatch.ctl(5). The default value is C<8000>. +units (normally kilobytes), at which innd(8) will be throttled by +innwatch(8), assuming a default F. The default value is +C<8000>. =back @@ -865,7 +886,8 @@ =item I Whether to start cnfsstat(8) when innd(8) is started. cnfsstat will log -the status of all CNFS cycbuffs to syslog on a periodic basis. This is a +the status of all CNFS cycbuffs to syslog on a periodic basis (frequency +is the default for C, currently 600 seconds). This is a boolean value and the default is false. =item I @@ -921,8 +943,10 @@ =item I -Where to write history statistics. It's not logged unless specified. -This can be disabled by ctlinnd(8) after innd runs. +Where to write history statistics for analysis with +F; this can be modified with ctlinnd(8) while innd is +running. Logging does not occur unless a path is given, and there is no +default value. =item I @@ -973,11 +997,12 @@ =item I -The threshold whether moving already read data to the top of buffer or -extending buffer. The buffer described here is used for reading NNTP data. -For those systems which do not have enough memory should not use higher value. -The default value is 8192. The value is allowed to be between 0 and 1048576, -and the value out of range is treated as 1048576. +The threshold for deciding whether to move already-read data to the top of +buffer or extend the buffer. The buffer described here is used for reading +NNTP data. Increasing this value may improve performance, but it should +not be increased on Systems with insufficient memory. Permitted values +are between C<0> and C<1048576> (out of range values are treated as +C<1048576>) and the default value is C<8192>. =item I @@ -986,29 +1011,28 @@ =item I -When overview retrieval which means responding 'XOVER' or running -expireover, buffindexed mmap's all overview data blocks which include -requested overview data internally for newsgroup. But for high volumed -newsgroups like control.cancel, it will try to do too many mmapping at -once, and this may lead to system resource problem. To avoid this, -buffindexed mmap's just one overview block(8KB), if it will try to mmap -over "keepmmappedthreshold * 1024"(bytes). This parameter is specific -to buffindexed overview storage method. The default value is C<1024> -(1MB). +When using buffindexed, retrieving overview data (that is, responding to +XOVER or running expireover) causes mmapping of all overview data blocks +which include requested overview data for newsgroup. But for high volume +newsgroups like control.cancel, this may cause too much mmapping at once +leading to system resource problems. To avoid this, if the amount to be +mmapped exceeds I (in KB), buffindexed mmap's just +one overview block (8 KB). This parameter is specific to buffindexed +overview storage method. The default value is C<1024> (1 MB). =item I -If set to anything other than C<0>, maximun buffer size for reading NNTP -command will have this value. It should not be large for system which is -slow to process and store articles. Otherwise innd(8) will stay for long -time at one channel to process and have other channels keep waiting for -long time. The default value is BUFSIZ defined in stdio.h(C<1024> in most -environment). +If set to anything other than C<0>, maximum buffer size (in bytes) for +reading NNTP command will have this value. It should not be large on +systems which are slow to process and store articles, as that would lead +to innd(8) spending a long time on each channel and keeping other channels +waiting. The default value is BUFSIZ defined in stdio.h (C<1024> in most +environments, see setbuf(3)). =item I How many times to attempt a fork(2) before giving up. The default value -is 10. +is C<10>. =item I @@ -1032,16 +1056,16 @@ priority and can help overchan(8) keep up with incoming news (if that's the object, be sure overchan(8) isn't also set to a lower priority via I). The default value is C<0>, which will cause nnrpd(8) -processes spawned from innd(8) to use the value of I and -nnrpd(8) run as a daemon to use the system default priority. Note that +processes spawned from innd(8) to use the value of I, while +nnrpd(8) run as a daemon will use the system default priority. Note that for nnrpd(8) processes spawned from innd(8), this value will be ignored if set to a value lower than I. =item I Wait for this many seconds before noticing inactive channels. -Wait for this many seconds before innd processes article when it's paused -or the number of channel write failure exceeds I. The +Wait for this many seconds before innd processes articles when it's paused +or the number of channel write failures exceeds I. The default value is C<300>. =item I @@ -1061,8 +1085,8 @@ operating system will be used; this will normally be adequate on systems other than Solaris. Nearly all operating systems have some hard maximum limit beyond which this value cannot be raised, usually either 128, 256, -or 1024. The default value of this parameter is -1. Setting it to 256 on -Solaris systems is highly recommended. +or 1024. The default value of this parameter is C<-1>. Setting it to +C<256> on Solaris systems is highly recommended. =back @@ -1077,7 +1101,7 @@ =item I The path to where the news articles are stored (for storage methods other -than CNFS). The default value is I/spool. +than CNFS). The default value is I/articles. =item I @@ -1094,8 +1118,8 @@ =item I The path to the database files used and updated by the server (currently, -active, active.times, history and its indices, and newsgroups). The -default value is I/db. +F, F, F and its indices, and +F). The default value is I/db. =item I @@ -1176,6 +1200,7 @@ ovmethod: tradindexed pathhost: news.example.com pathnews: /usr/local/news + hismethod: hisv6 For a more comprehensive example, see the sample F distributed with INN and installed as a starting point; it contains all of the default Index: doc/pod/innd.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/innd.pod,v retrieving revision 1.3 diff -u -r1.3 innd.pod --- doc/pod/innd.pod 2001/05/14 04:15:12 1.3 +++ doc/pod/innd.pod 2002/12/03 04:43:22 @@ -21,18 +21,18 @@ As the master daemon, B should generally be started at boot and be always running. It listens to a Unix-domain datagram socket for commands to control its activites, commands that can be sent using ctlinnd(8). The -current status of B can be obtained by running C, or +current status of B can be obtained by running C, or for more detailed output, innstat(8). -B can be in one of three operating modes, running, paused, or +B can be in one of three operating modes: running, paused, or throttled. Running is the normal mode; when the server is throttled, it closes connections and rejects new ones. Paused is like a temporary throttle, suspending B's activities but not causing the server to -shut down connections. The mode is normally changed via ctlinnd(8), -either by various automated processes such as nightly article expiration -or by the news administrator, but B will also throttle itself if it -encounters ENOSPC errors in writing data or an excessive number of I/O -errors (among other problems). +shut down existing connections. The mode is normally changed via +ctlinnd(8), either by various automated processes (such as nightly article +expiration) or manually by the news administrator, but B will also +throttle itself if it encounters ENOSPC errors in writing data or an +excessive number of I/O errors (among other problems). B normally takes care of spawning nnrpd(8) to handle connections from news reading clients, but it can be run on a separate port from @@ -44,20 +44,21 @@ port 433 be used for B. The primary configuration files that control B's activities are -incoming.conf(5), which specifies what remote sites B will accept -connections from, newsfeeds(5), which specifies what is to be done with -incoming articles besides storing them, and inn.conf(5), which sets a wide +F, which specifies what remote sites B will accept +connections from, F, which specifies what is to be done with +incoming articles besides storing them, and F, which sets a wide variety of configuration parameters. Some parameters in inn.conf(5) can -also be set with command-line flags; in this case, the command-line flags +also be set with command-line flags; for these, the command-line flags take precedence if used. B should normally never be run directly. Among other problems, it must run as the news user or all sorts of file ownership problems may result, and normally the port it listens on (119 or 433) is privileged and must be opened by root. Instead, B should be started via -inndstart(8), a small setuid root program that opens the appropriate port, +inndstart(8), a small setuid-root program that opens the appropriate port, cleans up the environment, changes to the news user, and then runs -B, passing along any command-line arguments it is given to B. +B, passing along any command-line arguments. (To use IPv6, B +absolutely must be started by inndstart(8).) =head1 OPTIONS @@ -79,7 +80,7 @@ =item B<-c> I B normally rejects any article that is older (in days) than the -value of I in inn.conf(5). This option, if given, overrides +value of I in F. This option, if given, overrides the value of that setting. If I is 0, this check is suppressed and B will accept articles regardless of how old they are. @@ -92,13 +93,13 @@ =item B<-d>, B<-f> -B normally puts itself into the background, repoints its standard +B normally puts itself into the background, points its standard output and error to log files, and disassociates itself from the terminal. Using B<-d> prevents all of this, resulting in log messages being written to standard output; this is generally useful only for -debugging. Using B<-f> prevents the backgrounding and disassociation +debugging. Using B<-f> prevents the backgrounding and disassociation but still redirects output; it may be useful if you want to monitor B -with another program that would be confused by forks. +with a program that would be confused by forks. =item B<-H> I, B<-T> I, B<-X> I @@ -109,48 +110,48 @@ should not use these options unless you're having problems. The table used for this check is fixed at 128 entries and is used as a ring; the size was chosen to make calculating the index easy and to be fairly sure -that it won't run out of space. In practice, it is doubtful that even +that it won't run out of space. In practice, it is unlikely that even half the table will be used at any given moment. The B<-H> flag limits the number of times a host is allowed to connect to -the server per the time interval given by B<-X>. The default is 2. +the server per the time interval given by B<-X>. The default is C<2>. The B<-T> flag limits the total number of incoming connections per the -time interval given by B<-X>. The maximum value is 128, and the default -is 60. +time interval given by B<-X>. The maximum value is C<128>, and the +default is C<60>. =item B<-i> I B normally allows a maximum number of concurrent NNTP connections given by the value of I in F. This option, if -given, overrides the value of that setting. If I is 0, this check -is suppressed. +given, overrides the value of that setting. If I is C<0>, this +check is suppressed. =item B<-I> I
-Normally if B binds to a port itself, it lets the operating system -pick the source IP address unless I is set in F. +Normally if B itself binds to a port, it lets the operating system +pick the source IP address (unless I is set in F). If this option is given, it specifies the IP address that INN should bind as. This is only relevant for servers with multiple local IP addresses. -The IP address must be in dotted quad (nnn.nnn.nnn.nnn) format. +The IP address must be in dotted quad (C) format. This option is rarely useful since B should not be binding to a -port. Instead, use inndstart(8) and the equivalent B<-I> option to it. +port itself. Instead, use inndstart(8) and its analgous B<-I> option. =item B<-l> I B normally rejects any article larger than the value of I in F. This option, if given, overrides the value of that setting and specifies a maximum article size of I. If -I is 0, this check is suppressed. +I is C<0>, this check is suppressed. =item B<-m> I -Normally B starts in the running mode. If this option is given, it -specifies what mode B should start in. I should begin with -one of C, C

, or C, and the starting mode will be set to running, -paused, or throttled respectively based on that initial letter. (C is -short for C.) +Normally B starts in the C mode. If this option is given, +it specifies what mode B should start in. I should begin with +one of C, C

, or C, and the starting mode will be set to +C, C, or C, respectively, based on that +initial letter. (C is short for C.) =item B<-N> @@ -162,7 +163,7 @@ Whether B allows (and hands off to B) reader connections while paused or throttled is normally determined by the value of -I in F. This option, if given, overrides +I in F is C, B will not allow readers if it is paused or throttled. If I is C, readers will be allowed regardless of B's operating mode. @@ -177,7 +178,7 @@ and only written out periodically. Normally you never need to use this option, since the number of outgoing -feeds is fixed, being the number of file feeds configured in newsfeeds(5), +feeds is fixed, being the number of file feeds configured in F, and is generally small (particularly given that innfeed(8) is now used for most outgoing feeds at large sites). @@ -188,16 +189,17 @@ suitable for listening to for incoming connections. This is how B tells B which open file descriptor is the network connection. If this flag is not given, B will attempt to open its -network socket itself; B always passes this flag to B. +network socket itself. B always passes this flag to B. =item B<-P> I The port B should listen on is normally given by the value of I in F. This option, if given, overrides that value and -specifies the port that B should bind to. Normally one should never -use this option and instead use B and its equivalent B<-P> -option. Since B should never be run as root, I has to be a -non-privileged port (one larger than 1024). +specifies the port that B should bind to. This option is rarely +useful since B normally does not bind itself; instead the analgous +B<-P> option to inndstart(8) should be used. Since B should never +be run as root, I has to be a non-privileged port (one larger than +1024). =item B<-r> @@ -226,8 +228,8 @@ =head1 CONTROL MESSAGES Arriving articles that have a Control header are called "control -messages." Except for cancel messages, these messages are handled by -controlchan(8) via a feed set up in newsfeeds(5). +messages". Except for cancel messages, these messages are handled by +controlchan(8) via a feed set up in F. (Cancel messages update the history database, so they must be handled internally; the cost of syncing, locking, then unlocking would be too high @@ -246,7 +248,7 @@ regardless of whether the control messages would affect the newsgroups you're feeding that site, you can put the appropriate control newsgroup in the subscription list. For example, to feed all cancel messages to a -given remote site (normally a bad idea), add C to their +given remote site (normally a bad idea), add C to its subscription list. Normally it's best to exclude the control newsgroups from feeds to keep from sending your peers more control messages than they care about. @@ -278,7 +280,7 @@ Finally, articles posted to newsgroups beginning with C are treated specially. Provided that either that newsgroup exists in the active file or I is set in F, the remainder of the newsgroup -is taken to be a site name, as configured in newsfeeds(5), and the article +is taken to be a site name, as configured in F, and the article is sent to that site. If I is set, the article will be filed in the group named C (which must exist in the active file). For example, with I set, an article posted to C will @@ -319,7 +321,7 @@ A batch transfer command, XBATCH I, is provided. This command will read I bytes and store them for later processing by rnews(1) (which must be run separately, probably from cron). See -innxbatch(8) and the sendxbatches program for more details on this +innxbatch(8) and F for more details on this extension. =item 6. @@ -336,7 +338,7 @@ B modifies as few article headers as possible, although it could be better in this area. -Empty headers and headers that consist of nothing but whitespace are also +Empty headers and headers that consist of nothing but whitespace are dropped. The local site's name (as set with the I parameter in @@ -350,7 +352,7 @@ A Lines: header will be added if the article was missing one. B does not rewrite incorrect headers. For example, it will not -replace an incorrect Lines header, but instead may reject such an article +replace an incorrect Lines header, though it may reject such an article depending on the value of I in F. =head1 CANCEL FEEDS @@ -361,17 +363,19 @@ socket (not to connections to any network sockets). To enter this mode, connect to the Unix domain socket (I/nntpin) -and send the command MODE CANCEL. The response will have code 284. Every -subsequent line sent on that connection should consist of a single message -ID. An attempt will be made to cancel that message ID, and the server -will reply 289 for success or 484 for failure. (Failure can occur in -circumstances such as the server being paused.) +and send the command MODE CANCEL. The response will have code C<284>. +Every subsequent line sent on that connection should consist of a single +message ID. An attempt will be made to cancel that message ID, and the +server will reply C<289> for success or C<484> for failure. (Failure can +occur, for example, if the server is paused or throttled, or the +Message-ID is corrupt. Failure does I occur if the article to be +cancelled does not exist.) =head1 LOGGING -B reports all incoming articles in its log file. This is a text -file with a variable number of space-separated fields in one of the -following formats: +B reports all incoming articles in its log file (I/news). +This is a text file with a variable number of space-separated fields in +one of the following formats: mon dd hh:mm:ss.mmm + feed site ... mon dd hh:mm:ss.mmm j feed site ... @@ -402,7 +406,7 @@ later. If the fourth field is a minus sign, then the article was rejected. The -reasons for rejection include: +reasons for rejection generated by B include: "%s" header too long "%s" wants to cancel <%s> by "%s" @@ -425,7 +429,9 @@ Unwanted distribution "%s" Whitespace in "Newsgroups" header -- "%s" -where C<%s>, above, is replaced by more specific information. +where C<%s>, above, is replaced by more specific information. (The Perl, +Python, andr Tcl filters, if used, may reject articles with other +reasons.) If the fourth field is the letter C, the article contains strange strings, such as CR without LF or LF without CR. (These characters should Index: doc/pod/inndf.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/inndf.pod,v retrieving revision 1.3 diff -u -r1.3 inndf.pod --- doc/pod/inndf.pod 2001/01/29 14:04:37 1.3 +++ doc/pod/inndf.pod 2002/12/03 04:43:22 @@ -17,18 +17,18 @@ INN's storage that df(1) doesn't understand. B doesn't sync, forks less, and is generally less complicated than df(1). -It's default behavior is to report free kilobytes (not disk blocks) or -free inodes if B<-i> is used in the file systems holding the directories +Its default behavior is to report free kilobytes (not disk blocks), or +free inodes if B<-i> is used, in the file systems holding the directories given on the command line. (A kilobyte in this case is 1024 bytes.) If only one directory is given, the output will be a simple number; if more than one directory is given, the output will be formatted for human readability. -If I set set to true in F, B can also be +If I is set to true in F, B can also be used to get information about the overview database. With the B<-n> option, it reports a count of the total number of overview records stored. With B<-o>, it reports the percentage of space used in the overview -database (for those overview methods where this is a meaningful question). +database (for those overview methods where this is meaningful data). =head1 OPTIONS @@ -54,7 +54,8 @@ =item B<-i> -Report the number of free inodes rather than the number of free kilobytes. +Report the number of free inodes rather than the amount of free disk +space. =item B<-n> Index: doc/pod/inndstart.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/inndstart.pod,v retrieving revision 1.3 diff -u -r1.3 inndstart.pod --- doc/pod/inndstart.pod 2001/01/08 02:14:49 1.3 +++ doc/pod/inndstart.pod 2002/12/03 04:43:23 @@ -12,9 +12,9 @@ open the privileged news transfer port, and then start innd(8), passing it the open file descriptor for the news port. B is used since only privileged programs can perform those two operations and since -B should not run privileged. It is installed setuid root and drops -privileges to the news user (set at configure time) before running -B. +B should not run with elevated privileges. It is installed setuid +root and drops privileges to the news user (as set at configure time) +before running B. Normally there is no need to run B directly. Instead, run rc.news(8) as the news user, and it will handle running B @@ -41,14 +41,14 @@ =item B<-P> I Bind to I instead of whatever is specified by I in -inn.conf(5). Note that this is subject to the constraints mentioned +F. Note that this is subject to the constraints mentioned above. =item B<-I> I

Bind as I
instead of whatever is specified by I in -inn.conf(5). The default behavior is to bind to INADDR_ANY, and that's -what's desired almost all the time. This option, and the inn.conf(5) +F. The default behavior is to bind to INADDR_ANY, and that's +what's desired almost all the time. This option, and the F parameter, may be useful if the machine has multiple interface cards and B should only be listening on a particular one. @@ -68,7 +68,7 @@ Ideally, everything about B's operations would be hard-coded so that it could not be modified. Fighting against this desire, however, is the ideal that as much of INN's operation as possible should be -configurable at run-time using inn.conf(5), and the news system should be +configurable at run-time using F, and the news system should be able to an alternate inn.conf by setting INNCONF to the path to that file before starting any programs. The configuration data therefore can't be trusted. @@ -88,10 +88,10 @@ =item * -As mentioned above, B will only bind to a very limited set of -ports below 1024. There are various attacks that can be performed using -random low-numbered ports, including exploits of the rsh family of -commands on some systems. +As mentioned above, B will only bind to a very limited subset +of ports below 1024. There are various attacks that can be performed +using random low-numbered ports, including exploits of the rsh(1) family +of commands on some systems. =item * @@ -123,7 +123,7 @@ other than 119, 433, or a port number given at configure time. This is not allowed for security reasons. If you're running B on a port other than 119 or 433, you need to give the --with-innd-port flag to -configure when you compile INN. +C when you compile INN. =item can't exec %s: %s @@ -133,13 +133,13 @@ =item can't getgrnam(%s) -(Fatal) Unable to determine the GID for the compiled-in news group. Is -the news group listed in /etc/group? +(Fatal) Unable to determine the GID for the compiled-in news group. +Perhaps the news group is not listed in F. =item can't getpwnam(%s) -(Fatal) Unable to determine the UID for the compiled-in news user. Is the -news user listed in /etc/passwd? +(Fatal) Unable to determine the UID for the compiled-in news user. +Perhaps the news user is not listed in F. =item can't open socket: %s @@ -149,24 +149,24 @@ =item can't set file descriptor limit to %d: %s (Warning) Unable to set the system file descriptor limit to the specified -value. Either that value is too high for your system or something else -went wrong. The file descriptor limit was left unchanged. Try changing -I in inn.conf to a smaller value. +value; the limit was left unchanged. Perhaps that value is too high for +your system. Try changing I in F to a smaller +value. =item can't set SO_REUSEADDR: %s -(Warning) B attempts to set SO_REUSEADDR so that if B -exits, it can be restarted again immediately without waiting for the port -to time out. For some reason, this failed, and that option was not set on -the port. +(Warning) B attempts to set SO_REUSEADDR using setsockopt(2) so +that if B exits, it can be restarted again immediately without +waiting for the port to time out. For some reason, this failed, and that +option was not set on the port. =item can't seteuid to %d: %s (Fatal) Unable to change the effective UID. If B has the -correct permissions (setuid root) and seteuid() to root (UID 0) is -failing, this may mean that your system has seteuid() but doesn't have -support for POSIX saved UIDs. If this is the case, please report this to -the INN maintainers. +correct permissions (setuid root) and seteuid to root (UID 0) is failing, +this may mean that your system has seteuid(2) but doesn't have support for +POSIX saved UIDs. If this is the case, please report this to the INN +maintainers. =item can't setgid to %d: %s @@ -191,8 +191,9 @@ =item invalid bindaddress in inn.conf (%s) -(Fatal) The I specified in inn.conf could not be converted to -an IP address. See inn.conf(5) for more information about valid values. +(Fatal) The I specified in F could not be converted +to an IP address. See inn.conf(5) for more information about valid +values. =item invalid port %s (must be a number) @@ -219,8 +220,9 @@ =head1 EXAMPLES Normally, B is never run directly. However, a simple way to -just restart B without running any other auxilliary programs or -performing any of the other checks done by rc.news(8) is to just run: +just restart B (if it is not running) without running any other +auxilliary programs or performing any of the other checks done by +rc.news(8) is to just run: inndstart @@ -252,12 +254,12 @@ =item BIND_INADDR Passed verbatim from B's environment. This is used by various -programs to override the I parameter in inn.conf(5) and +programs to override the I parameter in F and therefore must be in B's environment for programs like innfeed(8). =item HOME -Set to I from inn.conf. +Set to I from F. =item LOGNAME @@ -265,13 +267,13 @@ =item PATH -Set to I from inn.conf, I from inn.conf, and then /bin, -/usr/bin, and /usr/ucb in that order. +Set to I from F, I from F, and then +F, F, and F in that order. =item SHELL Set to the path to the system Bourne shell as determined by configure -(probably /bin/sh). +(probably F). =item TMPDIR Index: doc/pod/innmail.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/innmail.pod,v retrieving revision 1.1 diff -u -r1.1 innmail.pod --- doc/pod/innmail.pod 2001/01/23 09:50:21 1.1 +++ doc/pod/innmail.pod 2002/12/03 04:43:23 @@ -14,7 +14,7 @@ it to the specified addresses by invoking the value of I in F. -At least one address (formatted for the MTA specified in F if it +At least one address (formatted for the MTA specified in F, if it matters) is required. B will sanitize the addresses so that they contain only alphanumerics and the symbols C<@>, C<.>, C<->, C<+>, C<_>, and C<%>. Index: doc/pod/innupgrade.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/innupgrade.pod,v retrieving revision 1.1 diff -u -r1.1 innupgrade.pod --- doc/pod/innupgrade.pod 2002/09/01 22:22:17 1.1 +++ doc/pod/innupgrade.pod 2002/12/03 04:43:23 @@ -11,16 +11,16 @@ =head1 DESCRIPTION B is intended to be run during a major upgrade of INN to fix -the configuration files for any required changes. If given a directory, +the configuration files with any required changes. If given a directory, it will scan that directory for any files that it has updates defined for, -try to perform those updates, and replace the file with an updated version -if applying the updates resulted in any changes. The old version of the -file will be saved with a .OLD extension. +try to perform those updates, and replace the files with updated versions +if applying the updates resulted in any changes. The old versions of the +files will be saved with a C<.OLD> extension. If the B<-f> flag is used, only that file will be updated. If the file name doesn't match the standard file name of an INN configuration file, -the optional B<-t> flag may be given to specify the type. See L -for an example of this. +the optional B<-t> flag may be given to specify the type. See +L<"EXAMPLES"> for an example of this. Currently, B knows how to apply the following updates: @@ -38,7 +38,7 @@ Normally, B should be run on the I directory after any upgrade of INN other than a patch release (any upgrade that changes -the first or second version numbers). This may be done automatically by +the first or second version numbers). This may occur automatically during the upgrade process. =head1 OPTIONS @@ -73,7 +73,8 @@ innupgrade -t inn.conf -f inn-special.conf -Any upgrade rules that apply to F will be applied to that file. +Any upgrade rules that apply to F will be applied to the +alternate file. =head1 HISTORY Index: doc/pod/install.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/install.pod,v retrieving revision 1.45 diff -u -r1.45 install.pod --- doc/pod/install.pod 2002/11/25 20:55:09 1.45 +++ doc/pod/install.pod 2002/12/03 04:43:28 @@ -5,7 +5,7 @@ If you are upgrading from a previous major release of INN, it is recommended that you make copies of your old configuration files and use -them as guides for doing a clean installation and configuration of 2.3. +them as guides for doing a clean installation and configuration of 2.4. Many config files have changed, some have been added, and some have been removed. You'll find it much easier to start with a fresh install than to try to update your old installation. This is particularly true if you're @@ -19,36 +19,37 @@ after building INN and then comparing the new sample configuration files with your current ones to see if anything has changed. If you take this route, the old binaries, scripts, and man pages will be saved with an -extension of .OLD so that you can easily back out. Be sure to configure -INN with the same options that you used previously if you take this -approach (in particular, INN compiled with --enable-largefiles can't read -the data structures written by INN compiled without that flag and vice -versa). If you don't remember what options you used but you have your old -build tree, look at the comments at the beginning of F. +extension of C<.OLD> so that you can easily back out. Be sure to +configure INN with the same options that you used previously if you take +this approach (in particular, INN compiled with B<--enable-largefiles> +can't read the data structures written by INN compiled without that flag, +and vice versa). If you don't remember what options you used but you have +your old build tree, look at the comments at the beginning of +F. For more information about recent changes, see F. =head1 Supported Systems -So far as possible, INN is written in portable C and should work on any -Unix platform. It does, however, make extensive use of mmap() and certain -other constructs that may be poorly or incompletely implemented, +As much as possible, INN is written in portable C and should work on any +Unix platform. It does, however, make extensive use of mmap(2) and +certain other constructs that may be poorly or incompletely implemented, particularly on very old operating systems. INN has been confirmed to work on the following operating systems: - AIX 4.3 - FreeBSD 2.2.x and up - HP-UX 10.20 and up - Linux 2.x (tested with libc 5.4 or glibc 2.0 and up) - OpenBSD 2.8 and up - SCO 5.0.4 (tested with gcc 2.8.1 and cc) - Solaris 2.5.x and up - UnixWare 7.1 - UX/4800 R11 and up + AIX 4.3 + FreeBSD 2.2.x and up + HP-UX 10.20 and up + Linux 2.x (tested with libc 5.4, glibc 2.0 and up) + OpenBSD 2.8 and up + SCO 5.0.4 (tested with gcc 2.8.1, cc) + Solaris 2.5.x and up + UnixWare 7.1 + UX/4800 R11 and up If you have gotten INN working on an operating system other than the ones -listed above, please let us know at inn-bugs@isc.org. +listed above, please let us know at . =head1 Before You Begin @@ -72,7 +73,9 @@ subsystems. INN is tested primarily with newer versions of Perl, so it's generally recommended that you install the latest stable distribution of Perl before compiling INN. For instructions on obtaining and installing -Perl, see . +Perl, see . Note +that you may need to use the same compiler and options (particularly +largefile support) for Perl and INN. If you're using a version of Perl prior to 5.6.0, you may need to make sure that the Perl versions of your system header files have been @@ -99,11 +102,12 @@ =item * If you want to enable support for authenticated control messages (this is -not required but is highly recommended) then you will need to install some -version of PGP. The recommended version is GnuPG, since it's actively -developed, supports OpenPGP, is freely available and free to use for any -purpose (including in the US), and (as of version 1.0.4 at least) supports -RSA signatures used by most current control message senders. +not required, but is highly recommended for systems carrying public Usenet +hierarchies) then you will need to install some version of PGP. The +recommended version is GnuPG, since it's actively developed, supports +OpenPGP, is freely available and free to use for any purpose (in the US +and elsewhere), and (as of version 1.0.4 at least) supports the RSA +signatures used by most current control message senders. Alternately, you can install PGP from or one of the international versions of it. Be warned, however, that the licensing @@ -122,25 +126,27 @@ =head1 Unpacking the Distribution Released versions of INN are available from ftp.isc.org in F. -New major releases will be announed on inn-announce@isc.org (see +New major releases will be announed on (see F) when they're made. -If you want more a more cutting edge version, you can obtain current +If you want more a more cutting-edge version, you can obtain current snapshots from from ftp.isc.org in directory F. These -are snapshots of the current INN CVS tree taken daily; there are two -snapshots made every night (one of the current development branch, and one -of the stable branch consisting of bug fixes to the previous major -release). They are stored in date format; in other words the snapshots -from April 6th, 2000, would be named F and -F. Choose the newest file. +are snapshots of the INN CVS tree taken daily; there are two snapshots +made each night (one of the current development branch, and one of the +stable branch consisting of bug fixes to the previous major release). +They are stored in date format; in other words the snapshots from April +6th, 2000, would be named F and +F. Choose the newest file of whichever branch +you prefer. (Note that the downloading, configuring, and compiling steps +can be done while logged in as any user.) The distribution is in gzip compressed tar archive format. To extract it, execute: gunzip -c | tar -xf - -Extracting the source distribution will create a directory named F -(followed by a version number, -CURRENT, or -STABLE) where the source +Extracting the source distribution will create a directory named +F<< inn- >> or F<< inn-- >> where the source resides. =head1 Installing INN @@ -150,7 +156,7 @@ a group called C. The home directory of this user should be set to the directory under which you wish to install INN (F is the default and is a good choice). INN will install itself as this user -and group. You can change these if you want but these are the defaults +and group. You can change these if you want, but these are the defaults and it's easier to stick with them on a new installation. WARNING: By default, INN installs various configuration files as @@ -174,7 +180,10 @@ by the server. Particularly avoid doing anything in the news spool itself as root, and make sure you fix the ownership of any created files if you have to. INN doesn't like files in the news spool owned by a user other -than the news user. +than the news user. However, since certain binaries need to be setuid +root, indiscriminate use of C is not the solution. (If you +don't like to log in to system accounts, careful use of C on +directories and a umask of C<002> or C<007> may suffice.) INN uses GNU autoconf and a generated configure script to make configuration rather painless. Unless you have a rather abnormal setup, @@ -203,9 +212,9 @@ Sets the prefix for INN database files. The default is F, where PREFIX is F unless overridden with the option -above. This history and active files will be stored in this directory, -and writes to those files are an appreciable percentage of INN's disk -activity. The history file can also be quite large (requiring up to 2GB +above. The history and active files will be stored in this directory, and +writes to those files are an appreciable percentage of INN's disk +activity. The history file can also be quite large (requiring up to 2 GB or more during nightly expire), so this is a common portion of INN to move to a different file system. @@ -223,7 +232,8 @@ otherwise be set to a world-writeable directory, since INN doesn't take care to avoid symlink attacks and other security problems possible with a world-writeable directory. This directory should be reserved for the -exclusive use of INN and only writeable by the news user. +exclusive use of INN and only writeable by the news user. Usage is +generally light, so this is unlikely to need a separate partition. It's also possible to set the paths for most other sections of the INN installation independently; see C<./configure --help> and look for the @@ -254,7 +264,8 @@ written in Perl. Highly recommended, because many really good spam filters are written in Perl. See F for all the details. -Even if you do not use this option, INN still requires Perl to build. +Even if you do not use this option, INN still requires Perl as mentioned +above. =item B<--with-python> @@ -275,12 +286,12 @@ =item B<--with-innd-port>=PORT -By default, inndstart refuses to bind to any port under 1024 other than -119 and 433 for security reasons (to prevent attacks on rsh-based commands -and replacing standard system daemons). If you want to run innd on a -different port under 1024, you'll need to tell configure what port you -intend to use. (You'll also still need to set the port number in -F or by giving it to inndstart on the command line.) +By default, inndstart(8) refuses to bind to any port under 1024 other than +119 and 433 for security reasons (to prevent attacks on rsh(1)-based +commands and replacing standard system daemons). If you want to run innd +on a different port under 1024, you'll need to tell configure what port +you intend to use. (You'll also still need to set the port number in +F or give it to inndstart on the command line.) =item B<--with-syslog-facility>=FACILITY @@ -365,7 +376,7 @@ supporting programs. This option should be considered developmental at present. For more information see F (and if you have any particularly good or bad news to report, please let us know at -inn-bugs@isc.org). +). =back @@ -393,25 +404,26 @@ make install You will need to run this command as root so that INN can create the -directories it needs and install a couple of setuid wrapper scripts needed -to raise resource limits and allow innd to bind to port 119. This will -install INN under the install directory (F, unless you -specified something else to the configure script.) +directories it needs, change ownerships (if you did not compile as the +news user) and install a couple of setuid wrapper programs needed to raise +resource limits and allow innd to bind to ports under 1024. This step +will install INN under the install directory (F, unless +you specified something else to the configure script). -If you use SSL support for nnrp, you must make a certificate and private -key at least once. Type: +If you are configuring SSL support for newsreaders, you must make a +certificate and private key at least once. Type: make cert as root in order to do this. -You are now ready for the really fun part: configuring your copy of INN! +You are now ready for the really fun part: configuring your copy of INN! =head1 Choosing an Article Storage Format The first thing to decide is how INN should store articles on your system. -There are four different methods for you to choose from, all of which have -their own advantages and disadvantages. INN can support all four at the +There are four different methods for you to choose from, each of which has +its own advantages and disadvantages. INN can support all four at the same time, so you can store certain newsgroups in one method and other newsgroups in another method. @@ -487,8 +499,8 @@ Disadvantages: Article retention times are more difficult to control because old articles are overwritten automatically. Attacks on Usenet, -such as flooding or massive amounts of spam, can cause wanted articles to -expire much faster than you intended with no warning. +such as flooding or massive amounts of spam, can result in wanted articles +expiring much faster than you intended (with no warning). =back @@ -504,36 +516,36 @@ hierarchies and hierarchies that should never expire in tradspool. If your news server will be supporting readers, you'll also need to choose -an overview storage mechanism (by setting ovmethod in F). There -are three overview mechanisms to choose from: tradindexed, buffindexed, -and ovdb. tradindexed is very fast for readers, but it has to update two -files for every incoming article and can be quite slow to write. -buffindexed can keep up with a large feed more easily, since it uses large -buffers to store all overview information in, but it's somewhat slower for -readers (although not as slow as the unified overview in INN 2.2). ovdb -stores overview data in a Berkeley DB database; it's fast and very robust, -but requires more disk space. See the ovdb(5) man page for more -information on it. +an overview storage mechanism (by setting I in F). +There are three overview mechanisms to choose from: tradindexed, +buffindexed, and ovdb. tradindexed is very fast for readers, but it has +to update two files for each incoming article and can be quite slow to +write. buffindexed can keep up with a large feed more easily, since it +uses large buffers to store all overview information, but it's somewhat +slower for readers (although not as slow as the unified overview in INN +2.2). ovdb stores overview data in a Berkeley DB database; it's fast and +very robust, but requires more disk space. See the ovdb(5) man page for +more information on it. Note that ovdb has not been as widely tested as the other overview mechanisms and should be considered experimental. If buffindexed is chosen, you will need to create the buffers for it to use (very similar to creating CNFS buffers) and list the available buffers -in buffindexed.conf. See buffindexed.conf(5) for more information. +in F. See buffindexed.conf(5) for more information. =head1 Configuring INN All documentation from this point on assumes that you have set up the news user on your system as suggested in L so that the root of your INN installation is F<~news/>. If you've moved things around by -using options with configure, you'll need to adjust the instructions to +using options with C, you'll need to adjust the instructions to account for that. All of INN's configuration files are located in F<~news/etc>. Unless noted otherwise, any files referred to below are in this directory. When -you first install INN, samples of each file (containing lots of comments) -are installed in F<~news/etc>; refer to them for concrete examples of +you first install INN, a sample of each file (containing lots of comments) +is installed in F<~news/etc>; refer to these for concrete examples of everything discussed in this section. All of INN's configuration files, all of the programs that come with it, @@ -549,7 +561,7 @@ man -M ~news/man inn.conf -to see the man page for F (for example). +to see the inn.conf(5) man page (for example). Before we begin, it is worth mentioning the wildmat pattern matching syntax used in many configuration files. These are simple wildcard @@ -585,15 +597,16 @@ See uwildmat(3) for full details on wildmat patterns. In all INN configuration files, blank lines and lines beginning with a -C<#> symbol are considered comments and are ignored. +C<#> symbol are considered comments and are ignored. Be careful, not all +files permit comments to begin in the middle of the line. =head2 inn.conf The first, and most important file is F. This file is organized as a series of parameter-value pairs, one per line. The parameter is -first, followed by a colon and one or more whitespace characters and the -value itself. For some parameters the value is a string or a number; for -others it is true or false. (True values can be written as C, +first, followed by a colon and one or more whitespace characters, and then +the value itself. For some parameters the value is a string or a number; +for others it is true or false. (True values can be written as C, C, or C, whichever you prefer. Similarly, false values can be written as C, C, or C.) @@ -609,13 +622,13 @@ While this can be an expensive operation, its speed has been improved considerably as of INN 2.3 and it's probably safe to turn on without risking excessive server load. The default is true. (Note that the -access: setting in F overrides this value; see +I setting in F overrides this value; see readers.conf(5) for more details.) =item complaints -Used to set the value of the X-Complaints-To: header which is added to all -articles posted locally. The usual value would be something like +Used to set the value of the X-Complaints-To: header, which is added to +all articles posted locally. The usual value would be something like C or C. If not specified, the newsmaster email address will be used. @@ -624,50 +637,53 @@ Sets the domain name for your server. Normally this is determined automatically by INN, but in some cases it is necessary to set it manually. For example, if you are running NIS on a SunOS system I -your hostnames are not fully-qualified (ie, your systems are named "host" -instead of "host.example.com") then you will need to use this option to -set your domain name manually. If in doubt, leave this option commented -out or remove it completely. +your hostnames are not fully-qualified (i.e., your systems are named +"host" instead of "host.example.com") then you will need to use this +option to set your domain name manually. If in doubt, leave this option +commented out (or remove it completely). See I in readers.conf(5) +if you want to affect the righthand side of autogenerated Message-IDs. =item hiscachesize -The memory in kilobytes to allocate for a cache of recently used history -file entries. Setting this to 0 disables history caching. History -caching can greatly increase the number of articles per second that your -server is capable of processing. A value of 256 is a good default choice. +The amount of memory (in kilobytes) to allocate for a cache of recently +used history file entries. Setting this to 0 disables history caching. +History caching can greatly increase the number of articles per second +that your server is capable of processing. A value of C<256> is a good +default choice. =item logipaddr -If set to true (the default), INN will log the IP address of the remote -host from which it received an article. If set to false, the trailing -Path: header entry is logged instead. If you are using controlchan (see -below) and need to process ihave/sendme control messages (this is very, -very unlikely, so if you don't know what this means, don't worry about -it), make sure you set this to false, since controlchan needs a site name, -not an IP address. +If set to true (the default), INN will log the IP address (or hostname, if +the host is listed in F with a hostname) of the remote host +from which it received an article. If set to false, the trailing Path: +header entry is logged instead. If you are using controlchan (see below) +and need to process ihave/sendme control messages (this is very, very +unlikely, so if you don't know what this means, don't worry about it), +make sure you set this to false, since controlchan needs a site name, not +an IP address. =item organization Set this to the name of your organization as you want it to appear in the -Organization: header of all articles posted locally not already containing -that header. This will be overridden by the value of the ORGANIZATION -environment variable (if it exists). If neither this parameter nor the -environment variable or set, no Organization: header will be added to -posts without one. +Organization: header of all articles posted locally and not already +containing that header. This will be overridden by the value of the +ORGANIZATION environment variable (if it exists). If neither this +parameter nor the environment variable or set, no Organization: header +will be added to posts which lack one. =item pathhost This is the name of your news server as you wish it to appear in the Path: header of all postings which travel through your server (this includes local posts and incoming posts that you forward out to other sites). If -no pathhost is specified then the fully-qualified domain name (FQDN) of +this parameter is unspecified, the fully-qualified domain name (FQDN) of the machine will be used instead. Please use the FQDN of your server or an alias for your server unless you have a very good reason not to; a future version of the news RFCs may require this. =item rlimitnofile -If set to a non-negative value (the default is -1), INN (both innd and +If set to a non-negative value (the default is C<-1>), INN (both innd and innfeed) will try to raise the maximum number of open file descriptors to this value when it starts. This may be needed if you have lots of incoming and outgoing feeds. Note that the maximum value for this setting @@ -688,7 +704,7 @@ F determines how incoming articles are redistributed to your peers and to other INN processes. F is very versatile and contains dozens of options; we will touch on just the basics here. -newsfeeds(5) contains more detailed information. +The manpage contains more detailed information. F is organized as a series of feed entries. Each feed entry is composed of four fields separated by colons. Entries may span multiple @@ -713,9 +729,9 @@ The second field specifies a set of desired newsgroups and distribution lists, given as newsgroup-pattern/distribution-list. The distribution -list is not described here; newsfeeds(5) for information (it's not used -that frequently in practice). The newsgroup pattern is a wildmat-style -pattern list as described above (supporting C<@>). +list is not described here; see newsfeeds(5) for information (it's not +used that frequently in practice). The newsgroup pattern is a +wildmat-style pattern list as described above (supporting C<@>). The third field is a comma-separated list of flags that determine both the type of feed entry and sets certain parameters for the entry. See @@ -735,7 +751,7 @@ references to articles. Now that you have a rough idea of the file layout, we'll begin to add the -actual feed entries. First we'll set up the special ME entry. This entry +actual feed entries. First, we'll set up the special ME entry. This entry is required and serves two purposes: the newsgroup pattern specified here is prepended to the newsgroup list of all other feeds, and the distribution pattern for this entry determines what distributions (from @@ -748,21 +764,21 @@ specifically from every feed instead. The ME entry tends to confuse a lot of people, so this point is worth -repeating: The newsgroup patterns set the default subscription for +repeating: the newsgroup patterns set the default subscription for I feeds, and the distribution patterns set the acceptable Distribution: header entries for I articles. This is confusing enough that it may change in later versions of INN. There are two basic ways to feed articles to remote sites. The most common for large sites and particularly for transit news servers is -innfeed, which sends articles to remote sites in real time (the article +innfeed(8), which sends articles to remote sites in real time (the article goes out to all peers that are supposed to receive it immediately after your server accepts it). For smaller sites, particularly sites where the only outgoing messages will be locally posted articles, it's more common to batch outgoing articles and send them every ten minutes or so from cron -using nntpsend and innxmit. Batching gives you more control and tends to -be extremely stable and reliable, but it's much slower and can't handle -lots of articles well. +using nntpsend(8) and innxmit(8). Batching gives you more control and +tends to be extremely stable and reliable, but it's much slower and can't +handle high volume very well. Batching outgoing posts is easy to set up; for each peer, add an entry to newsfeeds that looks like: @@ -773,41 +789,41 @@ where is the wildmat pattern for the newsgroups that site wants. In this example, the actual name of the remote site is -remote.example.com, but it puts news.example.com in the Path: header. If -the remote site puts its actual hostname in the Path: header, you won't +"remote.example.com", but it puts "news.example.com" in the Path: header. +If the remote site puts its actual hostname in the Path: header, you won't need the C part. -This entry will cause innd to write out a file in ~news/spool/outgoing -named remote.example.com and containing the message ID and storage token -of each message to send to that site. (The storage token is INN's +This entry will cause innd to write out a file in F<~news/spool/outgoing> +named F and containing the Message-ID and storage +token of each message to send to that site. (The storage token is INN's internal pointer to where an article is stored; to retrieve an article -given its storage token, use the program sm). innxmit knows how to read -this format of file and send those articles to the remote site. For +given its storage token, use sm(8)). F knows how to read files +of this format and send those articles to the remote site. For information on setting it up to run periodically, see L below. You will also need to set up a config file for -nntpsend; see the man page for F for more information. +F; see the man page for nntpsend.ctl(5) for more information. -If instead you want to use innfeed to send outgoing messages (recommended -for sites with more than a couple of peers), you need some slightly more -complex magic. You still set up a separate entry for each of your peers, -but rather than writing out batch files, they all "funnel" into a special -innfeed entry. That special entry collects all of the separate funnel -feeds and sends the data through a special sort of feed to an external -program, called a channel feed. +If instead you want to use F to send outgoing messages +(recommended for sites with more than a couple of peers), you need some +slightly more complex magic. You still set up a separate entry for each +of your peers, but rather than writing out batch files, they all "funnel" +into a special innfeed entry. That special entry collects all of the +separate funnel feeds and sends the data through a special sort of feed to +an external program (F in this case); this is a "channel" feed. -First, the special channel feed entry for innfeed that will collect all +First, the special channel feed entry for F that will collect all the funnel feeds: innfeed!\ :!*\ :Tc,Wnm*:/usr/local/news/bin/startinnfeed -y -(adjust the path to startinnfeed if you installed it elsewhere). Note +(adjust the path to startinnfeed(1) if you installed it elsewhere). Note that we don't feed this entry any articles directly (its newsgroup pattern is C). Note also that the name of this entry ends in an exclamation point. This is a standard convention for all special feeds; since the delimiter for the Path: header is C, no site name containing that -character can match the name of a real site. +character can ever match the name of a real site. Next, set up entries for each remote site to which you will be feeding articles. All of these entries should be of the form: @@ -817,15 +833,15 @@ :Tm:innfeed! specifying that they funnel into the C feed. As in the previous -example for batching, remote.example.com is the actual name of the remote -peer, news.example.com is what they put in the Path: header (if different -than the actual name of the server), and is the wildmat -pattern of newsgroups they want. - -As an alternative to NNTP, inn may also be fed to an IMAP server, by -creating a new executable almost identical to innfeed called imapfeed. -The startinnfeed process is modified such that it can be told to start -imapfeed instead of innfeed. The feed entry for this is as follows: +example for batching, "remote.example.com" is the actual name of the +remote peer, "news.example.com" is what it puts in the Path: header (if +different than the actual name of the server), and is the +wildmat pattern of newsgroups to be sent. + +As an alternative to NNTP, INN may also feed news out to an IMAP server, +by using imapfeed(8), which is almost identical to F. The +F process can be told to start F instead of +F. The feed entry for this is as follows: imapfeed!\ :!*\ @@ -837,38 +853,38 @@ :\ :Tm:imapfeed! -For more information on imapfeed, look at the imap_connection.c in the -innfeed directory. For more information on IMAP in general, look at -RFC 2060. - -Finally, there is a special entry for controlchan for processing newsgroup -control messages that should always be in F unless you never -want to honor any newsgroup control messages. This entry should look +For more information on F, look at the +F. For more information on IMAP in general, +see RFC 2060. + +Finally, there is a special entry for controlchan(8), which processes +newsgroup control messages, that should always be in F unless +you never want to honor any control messages. This entry should look like: controlchan!\ :!*,control,control.*,!control.cancel\ :Tc,Wnsm:/usr/local/news/bin/controlchan -(modified for the actual path to controlchan if you put it somewhere +(modified for the actual path to F if you put it somewhere else). See L for more details. For those of you upgrading from earlier versions of INN, note that the -functionality of overchan and crosspost is now incorporated into INN and -neither of those programs are necessary. Unfortunately, crosspost +functionality of overchan(8) and F is now incorporated into INN +and neither of those programs is necessary. Unfortunately, F currently will not work even with the tradspool storage method. You can -still use overchan if you make sure to set useoverchan to true in +still use F if you make sure to set I to true in F so that innd doesn't write overview data itself, but be -careful; innd may accept articles faster than overchan can process the +careful: innd may accept articles faster than overchan can process the data. =head2 incoming.conf -This file specifies which machines are permitted to connect to your host -and feed it articles. Remote servers you peer with should be listed here. -Connections from hosts not listed in this file will (if you don't allow -readers) be rejected or (if you allow readers) be handed off to nnrpd and -checked against the access restrictions in F. +F file specifies which machines are permitted to connect to +your host and feed it articles. Remote servers you peer with should be +listed here. Connections from hosts not listed in this file will (if you +don't allow readers) be rejected or (if you allow readers) be handed off +to nnrpd and checked against the access restrictions in F. Start with the sample F and, for each remote peer, add an entry like: @@ -876,23 +892,23 @@ peer remote.example.com { } This uses the default parameters for that feed and allows incoming -connections from a machine named remote.example.com. If that peer could +connections from a machine named "remote.example.com". If that peer could be connecting from several different machines, instead use an entry like: peer remote.example.com { hostname: "remote.example.com, news.example.com" } -This will allow either remote.example.com or news.example.com to feed +This will allow either "remote.example.com" or "news.example.com" to feed articles to you. (In general, you should add new peer lines for each separate remote site you peer with, and list multiple host names using the -hostname key if one particular remote site uses multiple servers.) +I key if one particular remote site uses multiple servers.) -You can restrict the newsgroups a remote site is allowed to send you using -the same sort of pattern that newsfeeds uses. For example, if you want to -prevent example.com hosts from sending you any articles in the local.* -hierarchy (even if they're crossposted to other groups), change the above -to: +You can restrict the newsgroups a remote site is allowed to send you, +using the same sort of pattern that newsfeeds(5) uses. For example, if +you want to prevent "example.com" hosts from sending you any articles in +the C hierarchy (even if they're crossposted to other groups), +change the above to: peer remote.example.com { patterns: "*, @local.*" @@ -909,21 +925,22 @@ of connections the remote host will be allowed. See incoming.conf(5) for all the details. -Note for those familiar with older versions of INN: This file replaces +Note for those familiar with older versions of INN: this file replaces the old F configuration file. =head2 cycbuff.conf -This configuration file is only required if CNFS is used. If you aren't -using CNFS, skip this section. +F is only required if CNFS is used. If you aren't using +CNFS, skip this section. -CNFS stores articles in logical objects called metacycbuffs. Each of the -metacycbuffs is in turn composed of one or more physical buffers called -cycbuffs. As articles are written to the metacycbuff each article is +CNFS stores articles in logical objects called I. Each +metacycbuff is in turn composed of one or more physical buffers called +I. As articles are written to the metacycbuff, each article is written to the next cycbuff in the list in a round-robin fashion (unless -sequential mode is specified, in which case each cycbuff is filled before -moving on to the next). This is so that you can distribute the individual -cycbuffs across multiple physical disks and balance the load between them. +C mode is specified, in which case each cycbuff is filled +before moving on to the next). This is so that you can distribute the +individual cycbuffs across multiple physical disks and balance the load +between them. There are two ways to create your cycbuffs: @@ -932,7 +949,7 @@ =item 1. Use a raw disk partition (best). This will give you the most speed, but -it requires your OS support mmap() on a block device. Solaris supports +it requires your OS support mmap(2) on a block device. Solaris supports this, FreeBSD and Linux (without patches) do not. Also on many PC-based Unixes it is difficult to create more than eight partitions, which may limit your options. @@ -948,25 +965,28 @@ work regardless of your operating system. Now you need to decide on the sizes of your cycbuffs and metacycbuffs. -You'll probably want to separate the heavy-traffic groups (alt.binaries.* -and maybe a few other things like *.jobs* and news.lists.filters) into -their own metacycbuff so that they don't overrun the server and push out -articles on the more useful groups. If you have any local groups that you -want to stay around for a while then you should put them in their own -metacycbuff as well, so that they don't get pushed out by other traffic. -(Or store them in one of the other storage methods, such as tradspool.) +You'll probably want to separate the heavy-traffic groups +(C and maybe a few other things like C<*.jobs*> and +C) into their own metacycbuff so that they don't +overrun the server and push out articles on the more useful groups. If +you have any local groups that you want to stay around for a while then +you should put them in their own metacycbuff as well, so that they don't +get pushed out by other traffic. (Or you might store them in one of the +other storage methods, such as tradspool.) For each metacycbuff, you now need to determine how many cycbuffs will -make up the metacycbuff, the size of those cycbuffs and where they will be -stored. Some OSes do not support files larger than 2GB which will force -all of your cycbuffs to be < 2GB. Some versions of Linux are known to -have this limitation, FreeBSD does not. Some OSes that support large +make up the metacycbuff, the size of those cycbuffs, and where they will +be stored. Some OSes do not support files larger than 2 GB, which will +limit the size you can make a single cycbuff, but you can still combine +many cycbuffs into each metacycbuff. Some versions of Linux are known to +have this limitation; FreeBSD does not. Some OSes that support large files don't support block access to large raw partitions (Solaris prior to -Solaris 7 or not running in 64-bit mode is in this category); on those -OSes, if you want cycbuffs over 2GB, you'll have to use regular files. If -in doubt, keep your cycbuffs smaller than 2GB. Also when laying out your -cycbuffs, you will want to try to arrange them across as many physical -disks as possible (or use a striped disk array and put them all on that). +Solaris 7, or not running in 64-bit mode, is in this category); on those +OSes, if you want cycbuffs over 2 GB, you'll have to use regular files. +If in doubt, keep your cycbuffs smaller than 2 GB. Also, when laying out +your cycbuffs, you will want to try to arrange them across as many +physical disks as possible (or use a striped disk array and put them all +on that). For each cycbuff you will be creating, add a line to F like the following: @@ -977,7 +997,7 @@ simple like "BUFF00", "BUFF01", etc. is a decent choice, or you may want to use something that includes the SCSI target and slice number of the partition. SIZE is the buffer size in kilobytes (if you're trying to stay -under 2GB, keep your sizes below 2097152). +under 2 GB, keep your sizes below C<2097152>). Now, you need to tell INN how to group your cycbuffs into metacycbuffs. This is similar to creating cycbuff entries: @@ -1028,7 +1048,7 @@ method "trash" that accepts the article and throws it away). The first parameter is a wildmat pattern in the same format used by the -newsfeeds file, and determines what newsgroups are accepted by this +newsfeeds(5) file, and determines what newsgroups are accepted by this storage class. The second parameter is a unique number identifying this storage class and @@ -1036,12 +1056,14 @@ expiration, and for timehash and timecaf will set the top-level directory in which articles accepted by this storage class are stored. The easiest way to deal with this parameter is to just number all storage classes in -storage.conf sequentially. +F sequentially. The assignment of a particular number to a +storage class is arbitrary but I (since it is used in storage +tokens). The third parameter can be used to accept only articles in a certain size -range into this storage class. A of zero (or a missing -) means no upper limit (and of course a of 0 would mean -no lower limit, because an article is always great than zero bytes long). +range into this storage class. A of C<0> (or a missing +) means no upper limit (and of course a of C<0> would +mean no lower limit, because all articles are more than zero bytes long). If you don't want to limit the size of articles accepted by this storage class, leave this parameter out entirely. @@ -1056,7 +1078,7 @@ articles in this storage class. If you're using CNFS exclusively, just create one storage class for each -metacycbuff that you have defined (in F) and set the +metacycbuff that you have defined in F and set the newsgroups pattern according to what newsgroups should be stored in that buffer. @@ -1067,16 +1089,22 @@ to divide up your newsgroups based on how long you want to retain articles in those groups and create a storage class for each such collection of newsgroups. Make note of the storage class IDs you assign as they will be -needed when you edit the F file a bit later. +needed when you edit F a bit later. =head2 expire.ctl + +F sets the expiration policy for articles stored on the +server. Be careful, since the default configuration will expire most +articles after 10 days; in most circumstances this deletion is +I, so read this whole section carefully if you want to keep +local hierarchies forever. (See archive(8) for a way to automate backups +of important articles.) -This file sets the expiration policy for articles stored on the server. Only one entry is required for all storage classes; it looks like: /remember/:10 -This entry says how long to keep the message IDs for articles that have +This entry says how long to keep the Message-IDs for articles that have already expired in the history file so that the server doesn't accept them again. Occasionally, fairly old articles will get regurgitated somewhere and offered to you again, so even after you've expired articles from your @@ -1084,14 +1112,15 @@ while to ensure you don't get duplicates. INN will reject any articles more than a certain number of days old (the -artcutoff parameter in F, defaulting to 10); the number on the -C line should match that. +I parameter in F, defaulting to C<10>); the number on +the C line should match that. CNFS makes no further use of F, since articles stored in CNFS -buffers expire automatically when the buffer runs out of free space. For -other storage methods, there are two different syntaxes of this file, -depending on whether C is set in F. If it is -set to false, F takes entries of the form: +buffers expire automatically when the buffer runs out of free space (but +see the C<-N> option in expireover(8) if you really want to expire them +earlier). For other storage methods, there are two different syntaxes of +this file, depending on I in F. If it is set +to false, F takes entries of the form: ::: @@ -1100,10 +1129,10 @@ in that storage class (decimal values are allowed). For articles that don't have an Expires: header, those are the only two values that matter. For articles with an Expires: header, the other two values come into play; -the date given in the Expires: header of an article will be honored +the date given in the Expires: header of an article will be honored, subject to the contraints set by and . All articles in this storage class will be kept for at least days, regardless of their -Expires: header, and all articles in this storage class will be expired +Expires: headers, and all articles in this storage class will be expired after days, even if their Expires: headers specify a longer life. All three of these fields can also contain the special keyword C. @@ -1120,22 +1149,22 @@ :::: is a wildmat expression (C and C<@> not permitted, and only a -single expression, not a comma-separated set of them. Each expiration +single expression, not a comma-separated set of them). Each expiration line applies to groups matching the wildmat expression. is C for moderated groups, C for unmoderated groups, and C for groups -with any moderation status; the line only matches groups with a matching -expiration status. All of the other fields have the same meaning as -above. +with any moderation status; the line only matches groups with the +indicated expiration status. All of the other fields have the same +meaning as above. =head2 readers.conf -Provided that noreader is set to false in F, any connection from -a host that doesn't match an entry in F (and any connection -from a host that does match such an entry but that then issues a MODE -READER command) will be handed off to nnrpd, the part of INN that supports -newsreading clients. nnrpd uses F to determine whether a -given connection is allowed to read news, and if so what newsgroups they -can read and post to. +Provided that I is set to false in F, any connection +from a host that doesn't match an entry in F (as well as +any connection from a host that does match such an entry, but has issued a +MODE READER command) will be handed off to nnrpd(8), the part of INN that +supports newsreading clients. nnrpd uses F to determine +whether a given connection is allowed to read news, and if so what +newsgroups the client can read and post to. There are a variety of fairly complicated things that one can do with F, things like run external authentication programs that can @@ -1154,21 +1183,20 @@ access "all" { users: "*@example.com" newsgroups: "*" - access: "Read Post" } If you're running a server for one particular domain, want to allow all hosts within that domain to read and post to any group on the server, and want to deny access to anyone outside that domain, just use the above and change C in the above to your domain and you're all set. -Lots of examples of more complicated things are in the example file. +Lots of examples of more complicated things are in the sample file. =head1 Creating the Article Spool (CNFS only) If you are using actual files as your CNFS buffers, you will need to pre-create those files, ensuring they're the right size. The easiest way to do this is with dd. For each cycbuff in F, create the -buffer with the following commands as the news user: +buffer with the following commands (as the news user): dd if=/dev/zero of=/path/to/buffer bs=1k count=BUFFERSIZE chmod 664 /path/to/buffer @@ -1177,26 +1205,28 @@ specified in F. This will create a zero-filled file of the correct size; it may take a while, so be prepared to wait. -Here's a command that will print out the dd commands that you should run: +Here's a command that will print out the dd(1) commands that you should +run: awk -F: \ '/^cy/ { printf "dd if=/dev/zero of=%s bs=1k count=%s\n", $3, $4 }' \ - cycbuff.conf + ~news/etc/cycbuff.conf If you are using raw devices, you don't technically have to do anything at -all (since INN is capable of using the devices in /dev), but you probably -want to create special device files for those devices somewhere for INN's -private use. Not only is it more convenient to keep all of INN's stuff -together, the device files used by INN really should be owned by the news -user and group and you may not want to do that with the files in /dev. - -To create the device files for INN, use mknod with a type of b, getting -the major and minor device numbers from the existing devices in /dev. -There's a small shell script in cycbuff.conf(5) that may help with this. -Make sure to create the device files in the location INN expects them -(specified in F). +all (since INN is capable of using the devices in F), but you +probably want to create special device files for those devices somewhere +for INN's private use. It s more convenient to keep all of INN's stuff +together, but more importantly, the device files used by INN really should +be owned by the news user and group, and you may not want to do that with +the files in F. + +To create the device files for INN, use mknod(8) with a type of C, +getting the major and minor device numbers from the existing devices in +F. There's a small shell script in cycbuff.conf(5) that may help +with this. Make sure to create the device files in the location INN +expects them (specified in F). -Solaris users please note: On Solaris, do not use raw devices that +Solaris users please note: on Solaris, do not use raw devices that include the first cylinder of the disk. Solaris doesn't protect the superblock from being overwritten by an application writing to raw devices and includes it in the first cylinder of the disk, so unless you use a @@ -1207,13 +1237,13 @@ =head1 Creating the Database Files At this point, you need to set up the news database directory -(F<~news/db>). This directory will hold the active file (the list of -newsgroups you carry), the active.times file (the creator and creation +(F<~news/db>). This directory will hold the active(5) file (the list of +newsgroups you carry), the active.times(5) file (the creator and creation time of newsgroups created since the server was initialized), the -newsgroups file (descriptions for all the newsgroups you carry), and the -history file (a record of every article the server currently has or has -seen in the past few days, used to decide whether to accept or refuse new -incoming messages). +newsgroups(5) file (descriptions for all the newsgroups you carry), and +the history(5) file (a record of every article the server currently has or +has seen in the past few days, used to decide whether to accept or refuse +new incoming messages). Before starting to work on this, make sure you're logged on as the news user, since all of these files need to be owned by that user. This is a @@ -1232,15 +1262,17 @@ that, go to and download F and F from there; that will start you off with reasonably complete files. If you plan to only carry a small set of groups, the -default minimal F file installed by INN is a good place to start -and you can create additional groups after the server is running by using -C. +default minimal F file installed by INN is a good place to start; +you can create additional groups after the server is running by using +C. (Another option is to use actsync(8) to synchronize +your newsgroup list to that of another server.) C and C must exist as newsgroups in your active file for INN to start, and creating pseudogroups for the major types of control messages is strongly encouraged for all servers that aren't standalone. -C must also exist as a newsgroup if you have mergetogroups set in -F. +If you don't want these groups to be visible to clients, do I delete +them; simply hide them in F. C must also exist as a +newsgroup if you have mergetogroups set in F. Next, you need to create an empty history database. To do this, type: @@ -1286,7 +1318,7 @@ so don't copy and paste from these instructions. Type it in by hand and make sure you use a tab, or you'll get mysterious failures. You'll also want to make sure that news log messages don't fill your other log files -(INN generates a lot of log traffic); for every entry in +(INN generates a lot of log traffic); so for every entry in F that starts with C<*>, add C<;news.none> to the end of the first column. For example, if you have a line like: @@ -1314,8 +1346,8 @@ =head1 Setting Up the Cron Jobs -INN requires a special cron job to be set up on your system to run the -news.daily script, which performs daily server maintenance tasks such as +INN requires a special cron job to be set up on your system to run +news.daily(8) which performs daily server maintenance tasks such as article expiration and the processing and rotation of the server logs. Since it will slow the server down while it is running, it should be run during periods of low server usage, such as in the middle of the night. @@ -1333,9 +1365,9 @@ option list for news.daily. If you use the batching method to send news, also set up a cron job to run -nntpsend every ten minutes. nntpsend will run innxmit for all non-empty -pending batch files to send pending news to your peers. That cron entry -should look something like: +nntpsend(8) every ten minutes. nntpsend will run innxmit for all +non-empty pending batch files to send pending news to your peers. That +cron entry should look something like: 0,10,20,30,40,50 * * * * /usr/local/news/bin/nntpsend @@ -1345,35 +1377,36 @@ The parameters passed to news.daily in the above example are the most common (and usually the most efficient) ones to use. More information on -what these parameters do can be found in the news.daily man page. +what these parameters do can be found in the news.daily(8) man page. =head1 File Descriptor Limits INN likes to use a lot of file descriptors, particularly if you have a lot of peers. Depending on what your system defaults are, you may need to -make sure the default limit is increased for INN (particularly innd and -innfeed). This is vital on Solaris, which defaults (at least as of 2.6) -to an absurdly low limit of 64 file descriptors per process. - -One way to increase the number of file descriptors is to set rlimitnofile -in F to a higher value. This will cause startinnfeed and -inndstart, the setuid root wrapper scripts that start innfeed and innd -respectively, to increase the file descriptor limits before they run the -regular INN programs. Note, however, that INN won't be able to increase -the limits above the hard limits set by your operating system; on some -systems, that hard limit is 256 file descriptors (Linux, for example). On -others, like Solaris, it's 1024. Increasing the limit beyond that value -may require serious system configuration work. (On some operating -systems, it requires patching and recompiling the kernel. On Solaris it -can be changed in /etc/system, but for 2.6 or earlier the limit cannot be -increased beyond 1024 without breaking select() and thereby breaking all -of INN. For current versions of Linux, you may be able to change the -maximum by writing to /proc/sys/fs/file-max.) - -256 file descriptors will probably be enough for all but the largest site. -There is no harm in setting the limits higher than you actually need -(provided they're set to something lower than or equal to your system hard -limit). 256 is therefore a reasonable value to try. +make sure the default limit is increased for INN (particularly for innd +and innfeed). This is vital on Solaris, which defaults (at least as of +2.6) to an absurdly low limit of 64 file descriptors per process. + +One way to increase the number of file descriptors is to set +I in F to a higher value. This will cause both +startinnfeed and inndstart (the setuid root wrapper scripts that start +innfeed and innd, respectively) to increase the file descriptor limits +before they run the regular INN programs. Note, however, that INN won't +be able to increase the limits above the hard limits set by your operating +system; on some systems, that hard limit is normally 256 file descriptors +(Linux, for example). On others, like Solaris, it's 1024. Increasing the +limit beyond that value may require serious system configuration work. +(On some operating systems, it requires patching and recompiling the +kernel. On Solaris it can be changed in F, but for 2.6 or +earlier the limit cannot be increased beyond 1024 without breaking +select(2) and thereby breaking all of INN. For current versions of Linux, +you may be able to change the maximum by writing to +F.) + +256 file descriptors will probably be enough for all but the largest +sites. There is no harm in setting the limits higher than you actually +need (provided they're set to something lower than or equal to your system +hard limit). C<256> is therefore a reasonable value to try. If you're installing INN on a Solaris system, particularly if you're installing it on a dedicated news server machine, it may be easier to just @@ -1382,16 +1415,16 @@ set rlim_fd_cur = 256 -in F and rebooting. You can increase it all the way to 1024 -(and may need to if you have a particularly large site), but that can -cause RPC and some stdio applications to break. It therefore probably +in F and rebooting. You can increase it all the way to +C<1024> (and may need to if you have a particularly large site), but that +can cause RPC and some stdio applications to break. It therefore probably isn't a good idea on a machine that isn't dedicated to INN. =head1 Starting and Stopping the System -INN is started via the shell script rc.news. This must be run as the news -user and not as root. To start INN on system boot, you therefore want to -put something like: +INN is started via the shell script F. This must be run as the +news user and not as root. To start INN on system boot, you therefore +want to put something like: su - news -c /usr/local/news/bin/rc.news Index: doc/pod/libinnhist.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/libinnhist.pod,v retrieving revision 1.4 diff -u -r1.4 libinnhist.pod --- doc/pod/libinnhist.pod 2002/01/17 16:54:31 1.4 +++ doc/pod/libinnhist.pod 2002/12/03 04:43:28 @@ -69,9 +69,9 @@ The B function opens the history file designated by I using the mode I using the specified I. I may be -B to indicate that read only access to the history +B to indicate that read-only access to the history database is desired, or B for read/write access. History -methods are defined at build time; the current history method +methods are defined at build time; the history method currently available is "hisv6". On success a newly initialised history handle is returned, or B on failure. @@ -80,7 +80,7 @@ to how it should handle its data files; B indicates that the caller would like as much of the data to be kept on disk (and out of memory), B indicates that the data files should be kept -in main memory where possible and B that the files should +in main memory where possible and B that the files should be mmap()ed into the processes address space. B is typically used where a mass rebuild of the history database is being performed; the underlying history manager may assume that the caller will call @@ -101,16 +101,16 @@ associated with I to disk. B associates a cache used for speeding up HIScheck with -I. The cache will occuy approximately I bytes. +I. The cache will occupy approximately I bytes. B retrieves a token from I based on the passed I (normally the Message-ID). If no entry with an associated token can be found, B will return B. If a token is found -I, I and I are filled in with the message -arrival, expiry and posting times respectively (or zero if the time +I, I, and I are filled in with the message +arrival, expiry, and posting times respectively (or zero, if the time component is not available), in addition to I being set to the retrieved token and a function return value of B. Any of -arrived, expires, posted or token may be B in which case that +arrived, expires, posted, or token may be B in which case that component is not returned to the caller, without affecting the return value. @@ -119,8 +119,8 @@ B returns B, else B. B writes a new entry to the database I associated -with I. I, I, I specify the arrival, -posting and expiry time respectively; I and I may be +with I. I, I, and I specify the arrival, +posting, and expiry time respectively; I and I may be specifed as <= 0 in which case that component shall be treated as absent in the database. I is associated with the specified I. B returns B on success, or B on @@ -153,11 +153,11 @@ new database (and so merely see the callbacks), I may be set B. -If the underlying history mechanism needs to pause the server the -I string is used as an an argument to the `ctlinnd pause' -command, as such prior to calling B the server should be -reserved by the caller; if the caller wishes to inhibit pausing of the -server, passing B will achieve this. If I is not +If the underlying history mechanism needs to pause the server, the +I string is used as the argument to the `ctlinnd pause' +command, and as such the server should be reserved by the caller prior +to calling B; if the caller wishes to inhibit pausing of +the server, passing B will achieve this. If I is not B, then on successful return from B the server will be left paused and the caller should unpause it. @@ -166,46 +166,47 @@ If I() returns B it indicates that stored entity associated with token is no longer available (or no longer required), -but the history entry should be kept until it meets the I -constraint. If I() returns B the entry is kept as is in -the newly expired history database. +and therefore the associated history entry may be expired once it +meets the I constraint. If I() returns B the +entry is kept as-is in the newly expired history database. The I function is passed the arrival, posting and expiry times, in addition to the token associated with the entry. Note that -posting and/or expiry may be zero, but that token will never be +posting and/or expiry may be zero, but that the token will never be B (such entries are handled solely via the threshold mechanism). The storage token passed to the discrimination function -may updated if required (for example as might be needed by a +may updated if required (for example, as might be needed by a hierachical storage management implementation). Entries in the database with an arrival time less than I with no token associated with them are deleted from the database. -The parameter I is passed to the discrimination function and +The parameter I is passed to the discrimination function, and may be used for any purpose required by the caller. If the discrimination function attempts to access the underlying -database (for read or write) during the callback the behaviour is +database (for read or write) during the callback, the behaviour is unspecified. B provides an iteration function for the specified I -database. For every entry in the history database I is -invoked passing the I, arrival, posting and expiry times, in +database. For every entry in the history database, I is +invoked, passing the I, arrival, posting, and expiry times, in addition to the token associated with the entry. If the I() returns B the iteration is aborted and B returns B to the caller. To process the entire database in the presence of a running server, -I may be passed; if this argument is not B it is used as -an an argument to the `ctlinnd (reserve|pause|go)' commands. If -I is not passed and the server is running the behaviour of +I may be passed; if this argument is not B, it is used +as an an argument to the `ctlinnd (reserve|pause|go)' commands. If +I is B and the server is running, the behaviour of B is undefined. If the callback function attempts to access the underlying database -during the callback the behaviour is unspecified. +during the callback, the behaviour is unspecified. B returns statistics on the history cache mechanism; given a -handle I a struct histstats is returned detailing: +handle I, the return value is a I +detailing: =over 4 @@ -238,8 +239,8 @@ B returns a string describing the most recent error associated with I; the format and content of these strings is -history manager dependent. Note that on setting an error the history -API will call libinn's B function. +history manager dependent. Note that on setting an error, the history +API will call the B function from libinn(3). B provides a control interface to the underlying history manager. The I argument determines the type of the request @@ -250,27 +251,31 @@ =item C (const char **) Get the base file path which the history handle represents. I -should be a pointer to a value of type B. +should be a pointer to a location of type B. The +result must not later be passed to free(3). + =item C (const char *) Set the base file path which this history handle should use; typically this is used after an anonymous handle has been created using B. I should be a value of type B. +*> and will be copied before being stored internally. =item C (size_t *) Set an upper bound on how many history operations may be pending in core before being synced to permanent storage; B<0> indicates -unlimited. I should be a pointer to a value of type B. +unlimited. I should be a pointer to a value of type B and +will not be modified by the call. =item C (size_t *) Set a hint to the to the underlying history manager as to how many entries there are expected to be in the history database; B<0> indicates that an automatic or default sizing should be made. I -should be a pointer to a value of type B. +should be a pointer to a value of type B and will not be +modified by the call. =item C (bool *) @@ -278,7 +283,7 @@ when creating new ones; typically this option may be set to B if the administrator believes that the existing history database is corrupt and that ignoring it may help. I should be a pointer to a -value of type B. +value of type B and will not be modified by the call. =item C (time_t *) @@ -286,7 +291,7 @@ seconds, between stat(2)s of the history files checking for replaced files (as happens during expire); this option is typically used by nnrpd(8) like applications. I should be a pointer to a value of -type B. +type B and will not be modified by the call. =head1 HISTORY Index: doc/pod/makehistory.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/makehistory.pod,v retrieving revision 1.8 diff -u -r1.8 makehistory.pod --- doc/pod/makehistory.pod 2002/08/25 23:57:56 1.8 +++ doc/pod/makehistory.pod 2002/12/03 04:43:29 @@ -10,13 +10,13 @@ =head1 DESCRIPTION B rebuilds the history(5) text file, which contains a list of -message IDs of articles already seen by the server. It can also be used +Message-IDs of articles already seen by the server. It can also be used to rebuild the overview database. Note that the dbz(3) indexes for the history file are rebuilt by makedbz(8), not by B as in earlier versions of INN. -The default name of the history text file is I/history; to specify -a different name, use the B<-f> flag. +The default location of the history text file is I/history; to +specify an alternate location, use the B<-f> flag. By default, B will scan the entire spool, using the storage manager, and write a history line for every article. To also generate @@ -29,10 +29,10 @@ up with problems like out-of-order overview entries, excessively large overview buffers, and the like. -If you are using ovdb as your overview method, you will want to have the -ovdb processes running while rebuilding overview; otherwise, the Berkeley -DB transaction logs will be extremely large by the time makehistory -finishes. You can start them with ovdb_init(8). +If I in F is C, you should have the ovdb +processes running while rebuilding overview; otherwise, the Berkeley DB +transaction logs will be extremely large by the time makehistory finishes. +You can start them with ovdb_init(8). =head1 OPTIONS @@ -42,7 +42,7 @@ Append to the history file rather than generating a new one. If you append to the main history file, make sure innd(8) is throttled or not -running or you can corrupt the history. +running, or you can corrupt the history. =item B<-b> @@ -52,7 +52,7 @@ =item B<-e> Compute Bytes headers which is used for overview data. This option is valid -only if B<-O> flag is specified and overview.fmt includes C. +only if B<-O> flag is specified and F includes C. =item B<-f> I @@ -72,8 +72,8 @@ =item B<-I> Don't store overview data for articles numbered lower than the lowest -article number in active(5). This is useful if there are old articles on -disk for whatever reason that shouldn't be available to readers or put +article number in F. This is useful if there are for whatever +reason old articles on disk that shouldn't be available to readers or put into the overview database. =item B<-l> I @@ -96,25 +96,25 @@ Size the history database for approximately I pairs. Accurately specifying the size is an optimization that will create a more efficient database. (The size should be the estimated eventual size -of the file, typically the size of the old file.) +of the F file, typically the size of the old file, in lines.) =item B<-O> Create the overview database as well as the history file. Overview information is only required if the server supports readers; it is not -needed for a transit-only server. If you are using the C -overview storage method, erase all of your overview buffers before running -B with B<-O>. +needed for a transit-only server (see I in inn.conf(5)). +If you are using the C overview storage method, erase all of +your overview buffers before running B with B<-O>. =item B<-T> I If B<-O> is given, B needs a location to write temporary -overview data. By default, it uses I, set in inn.conf(5), but if +overview data. By default, it uses I, set in F, but if this option is given, the provided I is used instead. This is also used for temporary files created by sort(1) (which is invoked in the process of writing overview information since sorted overview information -writes faster). By default, sort usually uses /var/tmp; see the man page -for sort on your system to be sure. +writes faster). By default, sort usually uses your system temporary +directory; see the sort(1) man page on your system to be sure. =item B<-x> @@ -129,15 +129,15 @@ Here's a typical example of rebuilding the entire history and overview database, removing broken articles in the news spool. This uses the default temporary file locations and should be done while innd isn't -running or is throttled. +running (or is throttled). makehistory -b -f history.n -O -l 30000 -I This will rebuild the overview (if using C, erase the existing overview buffers before running this command) and leave a new -history file in history.n in I. To preserve all of the history +history file as C in I. To preserve all of the history entries from the old history file that correspond to rejected articles or -expired articles, use: +expired articles, follow the above command with: cd /usr/local/news/db awk 'NF == 2 { print }' < history >> history.n @@ -168,7 +168,7 @@ =item inn.conf -Read for I and I. +Read for I, I, and other settings. =item I/history @@ -190,6 +190,6 @@ =head1 SEE ALSO dbz(3), active(5), history(5), inn.conf(5), ctlinnd(8), innd(8), -makedbz(8), ovdb_init(8). +makedbz(8), ovdb_init(8), overview.fmt(5). =cut Index: doc/pod/news.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/news.pod,v retrieving revision 1.21 diff -u -r1.21 news.pod --- doc/pod/news.pod 2002/11/26 06:38:55 1.21 +++ doc/pod/news.pod 2002/12/03 04:43:30 @@ -4,11 +4,11 @@ change, options in F that contain whitespace or a few other special characters must be quoted with double quotes, and empty parameters (parameters with no value) are not allowed. INN 2.4 comes with a script, -innupgrade, that is run automatically on C that will attempt +innupgrade(8), run automatically during C, that will attempt to fix any problems that it finds with your F file, saving the -original as inn.conf.OLD. +original as F. -This change is the beginning of standardizing the parsing and syntax +This change is the beginning of standardization of parsing and syntax across all of INN's configuration files. The history subsystem now has a standard API that allows other backends to @@ -20,8 +20,8 @@ will tell INN to use the same history backend as was used in previous versions. -If you use Perl authentication for nnrpd (if nnrpdperlauth in inn.conf -is true), however, there have been major changes. See L<"Changes to +If you use Perl authentication for nnrpd (if I in +F is true), there have been major changes. See L<"Changes to Perl Authentication Support for nnrpd"> in F for details. The wildmat API has been renamed (to uwildmat and friends; see uwildmat(3) @@ -57,8 +57,8 @@ =item * -Variables can now be used in the newsfeeds file to make it easier to -specify a lot of similar feeds or feed patterns. See the newsfeeds(5) man +Variables can now be used in the F file to make it easier to +specify many similar feeds or feed patterns. See the newsfeeds(5) man page for more details. =item * @@ -70,7 +70,7 @@ =item * Thanks to code contributed by CMU, innfeed can now feed an IMAP server as -well as other NNTP servers. See the man page for innfeed for more +well as other NNTP servers. See the man page for innfeed(8) for more information. =item * @@ -90,6 +90,7 @@ The interface between external authenticators and nnrpd is now wrapped in a library, which should make it easier to write additional authenticators. +For example, see F. =item * @@ -101,8 +102,8 @@ =item * Two configure options have changed names: --with-tmp-path is now ---with-tmp-dir and --with-largefiles is now --enable-largefiles to improve -consistency and better match the autoconf option guidelines. +--with-tmp-dir, and --with-largefiles is now --enable-largefiles to +improve consistency and better match the autoconf option guidelines. =item * @@ -114,29 +115,29 @@ =item * -A new option tradindexedmmap has been added to inn.conf. If set to true -(the default) then the tradindexed overview method will use mmap() to -access its overview data (in 2.3 you couldn't control this, it always used -mmap). +A new option, I, has been added to F. If set +to true (the default), then the tradindexed overview method will use +mmap() to access its overview data (in 2.3 you couldn't control this; it +always used mmap). =item * -Two new options nfsreader and nfswriter have been added to inn.conf to aid -in building NFS based shared reader/writer platforms. On the writer -server configure nfswriter to true and on all of the readers configure -nfsreader to true; these options add calls to force data out to the NFS -server and force it to be read directly from the NFS server at the +Two new options, I and I, have been added to +F to aid in building NFS based shared reader/writer platforms. +On the writer server configure nfswriter to true and on all of the readers +configure nfsreader to true; these options add calls to force data out to +the NFS server and force it to be read directly from the NFS server at the appropriate moments. Note that it has only been tested on Solaris 8, using CNFS as the storage mechanism and tradindexed as the overview method. =item * -nnrpd now supports article injection via IHAVE. Any articles injected this -way must have Date, From, Message-ID, Newsgroups, Path and Subject +nnrpd now supports article injection via IHAVE. Any articles injected +this way must have Date, From, Message-ID, Newsgroups, Path, and Subject headers. X-Trace and X-Complaints-To headers will be added if the -appropriate options are set in readers.conf, but other headers will not be -modified/inserted (i.e. NNTP-Posting-Host, NNTP-Posting-Date, +appropriate options are set in F, but other headers will not +be modified/inserted (e.g. NNTP-Posting-Host, NNTP-Posting-Date, Organization, Lines, Cc, Bcc and To headers). =item * @@ -151,7 +152,7 @@ argument to the NEWGROUPS command specifying the "distributions" that the command was supposed to apply to. -Clients that use that argument will break. There is not believed to be +Clients that use that argument will break. There are not believed to be any such clients, and it's easy enough to just filter the returned list of newsgroups (which is generally fairly short) to achieve the same results. @@ -182,32 +183,31 @@ If you want to allow readers, or if you want to expire based on newsgroup name, you need to tell INN to generate overview data and pick an overview -method by setting ovmethod in inn.conf. See INSTALL and inn.conf(5) for -more details. +method by setting I in F. See INSTALL and inn.conf(5) +for more details. The code that generates the dbz index files has been split into a seperate -program, makedbz. makehistory still generates the base history file and -the overview information, but some of its options have been changed. To -rebuild the history and overview files, use: +program, F. F still generates the base history file +and the overview information, but some of its options have been changed. +To rebuild the history and overview files, use something like: makehistory -b -f history.n -O -T/usr/local/news/tmp -l 600000 -(Change the /usr/local/news/tmp path to some directory that has plenty of +(change the /usr/local/news/tmp path to some directory that has plenty of temporary space, and leave off -O if you're running a transit-only server and don't intend to expire based on group name, and therefore don't need -overview.) Or use: +overview.) Or if your overview is buffindexed, use: makehistory -b -f history.n -O -F -(This is suitable for the "buffindexed" overview backend.) Both will -generate a new history file as history.n and rebuild overview at the same -time. If you want to preseve a record of expired message IDs in the -history file, run: +Both will generate a new history file as F and rebuild overview +at the same time. If you want to preseve a record of expired message IDs +in the history file, run: awk 'NF==2 { print; }' < history >> history.n -to append them to the newly created history file. Look over the new -history file and make sure it looks right, then generate the new index +to append them to the new history file you created above. Look over the +new history file and make sure it looks right, then generate the new index files and move them into place: makedbz -s `wc -l has been replaced by F. +For reader machines, F has been replaced by F. There currently isn't a program to convert between the old format and the new format (if you'd like to contribute one, it would be welcomed -gratefully). The new file is unfortunately considerably more complex to -support its new capabilities; please carefully read the example +gratefully). The new file is unfortunately considerably more complex as +a result of its new capabilities; please carefully read the example F provided and the man page when setting up your initial configuration. The provided commented-out examples cover the most common installation (IP-based authentication for all machines on the local network). -INN makes extensive use of mmap for the new overview mechanisms, so at the -present time NFS-mounting the spool and overview from one central server -on multiple reader machines probably isn't feasible in this version. mmap -tends to interact poorly with NFS (at the least, NFS clients won't see -updates to the mapped files in situations where they should). (The +INN makes extensive use of mmap(2) for the new overview mechanisms, so at +the present time NFS-mounting the spool and overview on multiple reader +machines from one central server probably isn't feasible in this version. +mmap tends to interact poorly with NFS (at the least, NFS clients won't +see updates to the mapped files in situations where they should). (The preferred way to fix this would, rather than backing out the use of mmap or making it optional, to add support for Diablo-style header feeds and pull-on-demand of articles from a master server.) -The flags for overchan have changed, plus you probably don't want to run -overchan at all any more. Letting innd write overview data itself results -in somewhat slower performance, but is more reliable and has a better -failure mode under high loads. Writing overview data directly is the -default, so in a normal upgrade from 2.2 to 2.3 you'll want to comment out -or remove your overchan entry in F and set useoverchan to false -in F. +The flags for F have changed, plus you probably don't want to +run overchan at all any more. Letting innd write overview data itself +results in somewhat slower performance, but is more reliable and has a +better failure mode under high loads. Writing overview data directly is +the default, so in a normal upgrade from 2.2 to 2.3 you'll want to comment +out or remove your overchan entry in F and set useoverchan to +false in F. -crosspost is no longer installed, and no longer works (even with +F is no longer installed, and no longer works (even with traditional spool). If you have an entry for crosspost in F, remove it. @@ -256,7 +256,8 @@ the old spool. It's more reliable and ensures that everything gets put into the right place. The easiest way to do this is to generate, on your old server, a list of all of your existing article files and then feed -that list to innxmit. +that list to innxmit. Further details can be found in the FAQ at +I. If you are using a version of Cleanfeed that still has a line in it like: @@ -288,7 +289,7 @@ each group and can handle a higher incoming article rate while still being fast for readers. The third (ovdb) uses Berkeley DB to store overview information (so you need to have Berkeley DB installed to use it). The -ovmethod key in F chooses the overview method to use. +I key in F chooses the overview method to use. Note that ovdb has not been as widely tested as the other overview mechanisms and should be considered experimental. @@ -345,9 +346,9 @@ =item * -The build and installation system has been substantially overhauled. make -update now updates scripts as well as binaries and documentation, there is -better support for parallel builds (with make -j), there is less needless +The build and installation system has been substantially overhauled. +C now updates scripts as well as binaries and documentation, +there is better support for parallel builds (C), there is less make recursion, and far more of the system-dependent configuration is handled directly by autoconf. libtool build support (including shared library support) should be better than previous releases. @@ -388,7 +389,7 @@ =item * -inndf, a portable version of df(1) is supplied. +inndf, a portable version of df(1), is supplied. =item * Index: doc/pod/newsfeeds.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/newsfeeds.pod,v retrieving revision 1.3 diff -u -r1.3 newsfeeds.pod --- doc/pod/newsfeeds.pod 2002/08/23 18:02:55 1.3 +++ doc/pod/newsfeeds.pod 2002/12/03 04:43:32 @@ -277,7 +277,7 @@ =item f Don't send articles rejected by filters. This is only useful when -I is set in inn.conf(5). With that variable set, this +I is set in F. With that variable set, this lets one accept all articles but not propagate filtered ones to some sites. @@ -355,7 +355,7 @@ there are more file feeds than allowed by the system, they will be buffered internally in least-recently-used order. If the internal buffer grows bigger then I bytes, however, the data will be written out to -the appropriate file. The default value is 16KB. +the appropriate file. The default value is 16 KB. =item B I @@ -463,7 +463,7 @@ The site that fed the article to the server. This is taken from either the Path: header or the IP address of the sending site depending on the -value of I in inn.conf(5). If I is true and the IP +value of I in F. If I is true and the IP address is C<0.0.0.0> (meaning that the article was fed from localhost by a program like rnews(8)), the Path: header value will be sent instead. @@ -734,8 +734,9 @@ cancel messages provided that control.cancel exists. In this case, we also exclude any article with a distribution of C. B gets the storage API token, the name of the sending site -(for processing old-style ihave and sendme control messages), and the -message ID for each article. +(for processing old-style ihave and sendme control messages, be sure to +read about I in controlchan(8)), and the message ID for each +article. For many other examples, including examples of the special C site entry, see the example newsfeeds file distributed with INN. Also see the Index: doc/pod/nnrpd.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/nnrpd.pod,v retrieving revision 1.1 diff -u -r1.1 nnrpd.pod --- doc/pod/nnrpd.pod 2002/09/11 16:31:25 1.1 +++ doc/pod/nnrpd.pod 2002/12/03 04:43:32 @@ -18,7 +18,7 @@ Unlike innd(8) B supports all NNTP commands for user-oriented reading and posting. -B uses the readers.conf(5) file to control who is authorized to +B uses the F file to control who is authorized to access the Usenet database. When I in F is not 0, it will also reject connections if the load average is greater than that value (typically 16). @@ -168,7 +168,7 @@ specifying default distribution patterns, moderators list, a one-per-line description of the current set of newsgroups, a list of the automatic group subscriptions, or a listing of the -F(5) file. +F file. The command C is equivalent to the C command. This is a common extension. Index: doc/pod/qio.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/qio.pod,v retrieving revision 1.1 diff -u -r1.1 qio.pod --- doc/pod/qio.pod 2000/07/29 06:07:02 1.1 +++ doc/pod/qio.pod 2002/12/03 04:43:33 @@ -42,7 +42,7 @@ B opens the given file for reading. For regular files, if your system provides that information and the size is reasonable, QIO will use the block size of the underlying file system as its buffer size; -otherwise, it will default to a buffer of 8KB. Returns a pointer to use +otherwise, it will default to a buffer of 8 KB. Returns a pointer to use for subsequent calls, or NULL on error. B performs the same operation except on an already-open file descriptor (I must designate a file open for reading). Index: doc/pod/readers.conf.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/readers.conf.pod,v retrieving revision 1.21 diff -u -r1.21 readers.conf.pod --- doc/pod/readers.conf.pod 2002/11/13 21:32:16 1.21 +++ doc/pod/readers.conf.pod 2002/12/03 04:43:34 @@ -7,7 +7,8 @@ F in I specifies access control for nnrpd(8). It controls who is allowed to connect as a news reader and what they're allowed to do after they connect. nnrpd reads this file when it starts -up. +up. (The location I/readers.conf is only the default; the same +format applies to any file specified with C.) There are two types of entries in F: parameter/value pairs and configuration groups. Blank lines and anything after a number sign @@ -45,10 +46,13 @@ There are two basic types of configuration groups, auth and access. The auth group provides mechanisms to establish the identity of the user, who they are. The access group determines, given the user's identity, what -they're permitted to do. Writing a F file for your setup is -a two-step process, first assigning an identity to each incoming -connection using auth groups, and then giving each identity appropriate -privileges with access group. +that user ispermitted to do. Writing a F file for your +setup is a two-step process: first assigning an identity to each +incoming connection using auth groups, and then giving each identity +appropriate privileges with access group. We recommend I +intermingling auth groups and access groups in the config file; it is +often more sensible (in the absence of the I parameter) to put all +of the auth groups first, and all of the access groups below. A user identity, as established by an auth group, looks like an e-mail address; in other words, it's in the form "@" (or @@ -66,7 +70,10 @@ } The is used as a label for the group and is only for documentation -purposes. +purposes. (If your syslog configuration records the C +facility, the will appear in the debugging output of nnrpd. +Examining that output can be very helpful in understanding why your +configuration doesn't do what you expect it to.) A given auth group applies only to hosts whose name or IP address matches the wildmat expression given with the hosts: parameter (comma-separated @@ -80,23 +87,25 @@ connection is using SSL. For any connection from a host that matches that wildmat expression or -netblock, (the program given with the res: parameter, if -present) is run to determine the identity of the user just from the -connection information. If it fails, or if the res: parameter isn't -present, the user is assigned an identity of "@"; in -other words, the values of the default: and default-domain: parameters are -used. If only returns a username, is used as -the domain. +netblock, each (multiple res: lines may be present in a +block; they are run in sequence until one succeeds), if any, is run to +determine the identity of the user just from the connection information. +If all the resolvers fail, or if the res: parameter isn't present, the +user is assigned an identity of "@"; in other words, +the values of the default: and default-domain: parameters are used. If + only returns a username, is used as the +domain. If the user later authenticates via the AUTHINFO USER/PASS commands, the -provided username and password is passed to , the value of -the auth: or perl_auth: parameter (if present). If this succeeds and +provided username and password are passed to each +(multiple auth: or perl_auth: lines may be present in a block; they are +run in sequence until one succeeds), if any. If one succeeds and returns a different identity than the one assigned at the time of the -connection, it is matched against the available access groups again -and the actions the user is authorized to do may change. +connection, it is matched against the available access groups again and +the actions the user is authorized to do may change. When matching auth groups, the last auth group in the file that matches a -given connection or username/password combination is used. +given connection and username/password combination is used. An access group definition usually looks like: @@ -121,15 +130,15 @@ and matching users will be able to read any group that matches and post to any group that matches . You can also set several other things in the access group as well as override -various inn.conf(5) parameters for just that group of users. +various inn.conf(5) parameters for just a particular group of users. Just like with auth groups, when matching access groups the last matching -one in the file is used to determine the user's permissions. There is +one in the file is used to determine the user's permissions. There is an exception to this rule: if the auth group which matched the client contains the perl_access: parameter then the perl script given as -argument is used to dynamically generate an access group. This new +argument is used to dynamically generate an access group. This new access group is then used to determine the access rights of the -client. +client; the access groups in the file are ignored. There is one additional special case to be aware of. When forming particularly complex authentication and authorization rules, it is @@ -154,12 +163,13 @@ In this case, the two key: parameters bind this auth group with this access group. For any incoming connection matching "*.example.com" (assuming there isn't any later auth group that also matches such hosts), -no access group that doesn't have "key: special" will even be checked. +no access group that doesn't have "key: special" will even be considered. Similarly, the above access group will only be checked if the user was authenticated with an auth group containing "key: special". This -mechanism normally isn't useful. +mechanism normally isn't useful; there is almost always a better way to +achieve the same result. -Also note in the above that there's no default-domain: parameter, which +Also note in the example that there's no default-domain: parameter, which means that no domain is appended to the default username and the identity for such connections is just "". Note that some additional add-ons to INN may prefer that authenticated identities always return a @@ -205,48 +215,49 @@ A simple command line for a user resolver (shell metacharacters are not supported). If a full path is not given, the program executed must be in -I/auth/resolv. A resolver is an authentication program which -attempts to figure out the identity of the connecting user using nothing -but the connection information (in other words, a username and password -aren't used). An examples of a resolver would be a program that gets the -username from an ident callback or from the user's hostname. +the I/auth/resolv directory. A resolver is an authentication +program which attempts to figure out the identity of the connecting user +using nothing but the connection information (in other words, the user +has not provided a username and password). An examples of a resolver +would be a program that assigns an identity from an ident callback or +from the user's hostname. One auth group can have multiple res: parameters, and they will be tried -in the order they're listed in and the results of the first successful one +in the order they're listed. The results of the first successful one will be used. =item B A simple command line for a user authenticator (shell metacharacters are not supported). If a full path is not given, the program executed must be -located in I/auth/passwd. An authenticator is a program used to -handle a user-supplied username and password, via a mechanism such as -AUTHINFO USER/PASS. Like with res:, one auth group can have multiple -auth: parameters; they will be tried in order and the results of the first -successful one will be used. +located in the I/auth/passwd directory. An authenticator is a +program used to handle a user-supplied username and password, via a +mechanism such as AUTHINFO USER/PASS. Like with res:, one auth group +can have multiple auth: parameters; they will be tried in order and the +results of the first successful one will be used. See also perl_auth: +below. =item B -A path to a perl script for authentication. perl_auth: works exactly -like auth:, the only difference is that it calls the script given as -argument using the perl hook rather then an external -program. Multiple/mixed use of auth: and perl_auth: is permitted -within any auth group. Each method is tried in order as they appear in -the auth group. perl_auth: has some advantages over auth: in that it -provides the authentication program with additional information about -the client and the ability to return an error string. This parameter -is only valid if INN is compiled with Perl support (B<--with-perl> -passed to configure). More information may be found in the file -F. +A path to a perl script for authentication. The perl_auth: parameter +works exactly like auth:, except that it calls the named script using +the perl hook rather then an external program. Multiple/mixed use of +auth: and perl_auth: is permitted within any auth group; each method is +tried in order listed in F. perl_auth: has more power +than auth: in that it provides the authentication program with +additional information about the client and the ability to return an +error string. This parameter is only valid if INN is compiled with Perl +support (B<--with-perl> passed to configure). More information may be +found in F. =item B The default username for connections matching this auth group. This is the username assigned to the user at connection time if all resolvers fail or if there are no res: parameters. Note that it can be either a bare -username, in which case default-domain: is appended after an C<@> if set, -or a full identity string containing an C<@>, in which case it will be -used verbatim. +username, in which case default-domain: (if present) is appended after +an C<@>, or a full identity string containing an C<@>, in which case it +will be used verbatim. =item B @@ -260,8 +271,8 @@ =item B If this parameter is present, any connection matching this auth group will -have its privileges determined only by access groups containing a matching -key parameter. +have its privileges determined only by the subset of access groups +containing a matching key parameter. =item B @@ -271,15 +282,15 @@ =item B -A path to a perl script for dynamically generating an access group. If -an auth group is successful and contains a perl_access parameter, then -the argument perl script will be used to create an access group. This -group will then be used to determine the access rights of the client, -overriding any access groups in readers.conf. If and only if a sucessful -auth group contains the perl_access parameter, then readers.conf +A path to a perl script for dynamically generating an access group. If +an auth group matches successfully and contains a perl_access parameter, +then the argument perl script will be used to create an access group. +This group will then determine the access rights of the client, +overriding any access groups in F. If and only if a +sucessful auth group contains the perl_access parameter, F access groups are ignored and the client's rights are instead determined -dynamically. This parameter is only valid if INN is compiled with Perl -support (B<--with-perl> passed to configure). More information may be +dynamically. This parameter is only valid if INN is compiled with Perl +support (B<--with-perl> passed to configure). More information may be found in the file F. =back @@ -304,8 +315,8 @@ Like the newsgroups: parameter, but the client is only given permission to read the matching newsgroups. This parameter is often used with post: -(below) and cannot be used in the same access group with a newsgroups: -parameter. +(below) to specify some read-only groups; it cannot be used in the same +access group with a newsgroups: parameter. =item B @@ -354,7 +365,7 @@ =back -Note that if this parameter is given, I in inn.conf(5) is +Note that if this parameter is given, I in F is ignored for connections matching this access group and the ability of the client to use NEWNEWS is entirely determined by the presence of C in the access string. If you want to support NEWNEWS, make sure to include @@ -379,8 +390,8 @@ If this parameter is present, a client matching this block will be disconnected with a "Permission denied" message containing the contents -(a "reason") of this parameter. Some newsreaders will then display the -reason to the user. +(a "reason" string) of this parameter. Some newsreaders will then +display the reason to the user. =item B @@ -398,7 +409,7 @@ =item B -Used as the contact address in the help message returned by nnrpd(8) if +Used as the contact address in the help message returned by nnrpd(8), if the virtualhost: parameter is set to true. =item B @@ -422,19 +433,19 @@ =item B If set to true, nnrpd(8) will behave as if it's running on a server with a -different name. This affects the Path:, Message-ID:, and X-Trace: headers +different name. This may affect Path:, Message-ID:, and X-Trace: headers of posted articles, as well as the apparent Path: and Xref: headers of all -articles read by the client. One of pathhost: or domain: must be set in -the same access group if this parameter is set to true, and nnrpd(8) will +articles read by the client. Either pathhost: or domain: must be present +in the same access group if this parameter is set to true. nnrpd(8) will act as if the server name is the value of pathhost:, or domain: if -pathhost: isn't set or is set to the same value as in inn.conf(5). One of +pathhost: isn't set or is set to the same value as in F. One of these parameters must be set to something different than that set in -inn.conf. +F. =back In addition, all of the following parameters are valid in access groups -and override the global setting in inn.conf(5). See inn.conf(5) for the +and override the global setting in F. See inn.conf(5) for the descriptions of these parameters: addnntppostingdate, addnntppostinghost, backoff_auth, backoff_db, backoff_k, backoff_postfast, backoff_postslow, backoff_trigger, checkincludedtext, clienttimeout, complaints, domain, @@ -450,15 +461,16 @@ =item * -All auth groups are scanned and the ones that don't match the client IP -address are eliminated. +All auth groups are scanned and the ones that don't match the client +(due to hosts:, localaddress:, ssl_required:, etc) are eliminated. =item * -Each remaining auth group is scanned from the last to the first, and an +The remaining auth groups are scanned from the last to the first, and an attempt is made to apply it to the current connection. This means running res: programs, if any, and otherwise applying default:. The first auth -group to return a valid user is kept as the active auth group. +group (starting from the bottom) to return a valid user is kept as the +active auth group. =item * @@ -471,27 +483,38 @@ the user authenticates. =item * + +When the user authenticates, the auth groups are rescanned, and only the +matching ones which contain at least one auth: or perl_auth: line are +considered. These auth groups are scanned from the last to the first, +running auth: programs and perl_auth: scripts. The first auth group +(starting from the bottom) to return a valid user is kept as the active +auth group. + +=item * -When the user authenticates, all auth groups with auth: or perl_auth: -lines are then checked from the bottom up and the first one that -returns a valid user is kept as the default auth group. +Regardless of how an auth group is established, as soon as one is, that +auth group is used to assign a user identity by taking the result of the +successful res:, auth, or perl_auth: line (or the default: if necessary), +and appending the default-domain: if necessary. (If the perl_access: +parameter is present, see below.) =item * -Regardless of how an auth group is established, as soon as one is, the -user permissions are granted by scanning the access groups from bottom up -and finding the first match. Unless the established auth group -contains the perl_access: parameter, in which case the dyanmically -generated access group returned by the perl script is used. +Finally, an access group is selected by scanning the access groups from +bottom up and finding the first match. (If the established auth group +contained a perl_access: line, the dynamically generated access group +returned by the Perl script is used instead.) User permissions are granted +based on the established access group. =back =head1 EXAMPLES -Here is probably the simplest useful example of a complete readers.conf. -This gives permissions to read and post to all groups to any connections -from the example.com domain, and no privileges for anyone connecting from -anywhere else: +Probably the simplest useful example of a complete F, +this gives permissions to read and post to all groups to any connections +from the "example.com" domain, and no privileges for anyone connecting +elsewhere: auth example.com { hosts: "*.example.com, example.com" @@ -504,7 +527,7 @@ Note that the access realm has no users: key and therefore applies to any user identity. The only available auth realm only matches hosts in the -example.com domain, though, so any connections from other hosts will be +"example.com" domain, though, so any connections from other hosts will be rejected immediately. If you have some systems that should only have read-only access to the @@ -523,12 +546,12 @@ If those are put in the file after the above example, they'll take precedence (because they're later in the file) for any user coming from a -machine in the lab.example.com domain, and those users will only have read +machine in the lab.example.com domain, everyone will only have read access, not posting access. Here's a similar example for a news server that accepts connections from anywhere but requires the user to specify a username and password. The -username and password is first checked against an external database of +username and password are first checked against an external database of usernames and passwords, and then against the system shadow password file: auth all { @@ -544,26 +567,37 @@ When the user first connects, there are no res: keys and no default, so they don't receive any valid identity and the connection won't match any access groups (even ones with C). Such users receive nothing -but authentication required responses from nnrpd until they authenticate. +but authentication-required responses from nnrpd until they authenticate. If they then later authenticate, the username and password are checked first by running B with the B<-d> option for an external dbm file of encrypted passwords, and then with the B<-s> option to check the -shadow password database (note that ckpasswd may have to be setgid to a -shadow group to use this option). If both of those fail, the user will -continue to have no identity; otherwise, they will acquire some other -identity string (whatever username they specified, since the password was -valid) and the access group will match, giving them full access. +shadow password database (note that this option may require ckpasswd to +be setgid to a shadow group, and there are security considerations; see +ckpasswd(8) for details). If both of those fail, the user will continue +to have no identity; otherwise, an identity will be assigned (usually +the supplied username, perhaps with a domain appended, although an +authenticator technically can provide a completely different username +for the identity), and the access group will match, giving full access. + +It may be educational to consider how to combine the above examples; +general groups always go first. The order of the auth groups actually +doesn't matter, since the "hosts: example.com" one only matches +connections before username/password is sent, and the "auth: ckpasswd" +one only matches after; order would matter if either group applied to +both cases. The order of the access groups in this case does matter, +provided the newsgroups: lines differ; the access group with no users: +line needs to be first, with the "users: " group after. Finally, here's a very complicated example. This is for an organization -that has an internal hierarchy example.* only available to local shell -users, who are on machines where identd can be trusted. Dialup users have -to use a username and password, which is then checked against RADIUS. +that has an internal hierarchy "example.*" only available to local shell +users, who are on machines where identd can be trusted. Dialup users must +provide a username and password, which is then checked against RADIUS. Remote users have to use a username and password that's checked against a database on the news server. Finally, the admin staff (users "joe" and -"jane") can post anywhere, including the example.admin.* groups that are -read-only for everyone else, and are exempted from the Perl filter. For -an additional twist, posts from dialup users have their Sender header +"jane") can post anywhere (including the "example.admin.*" groups that are +read-only for everyone else), and are exempted from the Perl filter. For +an additional twist, posts from dialup users have their Sender: header replaced by their authenticated identity. Since this organization has some internal moderated newsgroups, the admin @@ -622,13 +656,13 @@ Note the use of different domains to separate dialup from shell users easily. Another way to do that would be with key: parameters, but this -provides slightly more intuitive identity strings. Note also that the +way provides slightly more intuitive identity strings. Note also that the fail access group catches not only failing connections from external users but also failed authentication of shell and dialup users and dialup users before they've authenticated. The identity string given for, say, dialup users before RADIUS authentication has been attempted matches both the dialup access group and the fail access group, since it's -@dialup.example.com, but the fail group is last so it takes +"@dialup.example.com", but the fail group is last so it takes precedence. The shell auth group has an auth: parameter so that users joe and jane @@ -643,6 +677,53 @@ they get their special privileges regardless of how they connect, whether the dialups, the shell machines, or even externally with a username and password. + +=head1 SECURITY CONSIDERATIONS + +In general, separate passwords should be used for NNTP wherever +possible; the NNTP protocol itself does not protect passwords from +casual interception, and many implementations (including this one) do +not "lock out" accounts or otherwise discourage password-guessing +attacks. So it is best to ensure that a compromised password has +minimal effects. + +Authentication using the AUTHINFO USER/PASS commands passes unencrypted +over the network. Extreme caution should therefore be used especially +with system passwords (e.g. C). Passwords can be +protected by using NNTP over SSL or through ssh tunnels, and this usage +can be enforced by a well-considered server configuration that only +permits certain auth groups to be applied in certain cases. Here are +some ideas: + +=over 4 + +=item * + +To restrict connections on the standard nntp port (119) to use SSL for +some (or all) of the auth groups to match, use the ssl_required: +parameter. + +=item * + +If you consider your local network (but not the internet) secure, have +some auth groups with a restrictive hosts: parameter; they would go +above, with ones having global applicability below. + +=item * + +Consider running a C (with C<-D>, or out of "super-server" +like inetd) on the nntps port (563) for clients that support SSL. You +can use the ssl_required: parameter, or C<-c> to specify an alternate +F if you want a substantially different configuration for +this case. + +=item * + +If you want to restrict an auth group to only match loopback connections +(for users running newsreaders on localhost or connecting via an ssh +tunnel), use the localaddress: parameter. + +=back =head1 HISTORY Index: doc/pod/readme.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/readme.pod,v retrieving revision 1.13 diff -u -r1.13 readme.pod --- doc/pod/readme.pod 2002/08/23 18:07:31 1.13 +++ doc/pod/readme.pod 2002/12/03 04:43:35 @@ -26,7 +26,7 @@ to their peers, and so on, resulting in "flood fill" propagation of news articles. -A news server performs three basic functions: It accepts articles from +A news server performs three basic functions: it accepts articles from other servers and stores them on disk, sends articles it has received out to other servers, and offers stored news articles to readers on demand. It additionally has to perform some periodic maintenance tasks, such as @@ -45,12 +45,12 @@ News Transport Protocol). INN supports accepting articles via either NNTP connections or via UUCP. -innd, the heart of INN, handles NNTP feeding connections directly; UUCP -newsfeeds use rnews (included in INN) to hand articles off to innd. Other -parts of INN handle feeding articles out to other news servers, most -commonly innfeed (for real-time outgoing feeds) or nntpsend and innxmit -(used to send batches of news created by innd to a remote site via -TCP/IP). INN can also handle outgoing UUCP feeds. +B, the heart of INN, handles NNTP feeding connections directly; +UUCP newsfeeds use B (included in INN) to hand articles off to +innd. Other parts of INN handle feeding articles out to other news +servers, most commonly B (for real-time outgoing feeds) or +B and B (used to send batches of news created by innd +to a remote site via TCP/IP). INN can also handle outgoing UUCP feeds. The part of INN that handles connections from newsreaders is nnrpd. @@ -94,8 +94,8 @@ and have fewer features, installing Perl 5.004 or later is recommended. If you want to enable PGP verification of control messages (highly -recommended), you will need to have PGP installed. See F for -more details. +recommended), you will need to have a PGP implementation installed. See +F for more details. =head1 Getting Started @@ -126,8 +126,8 @@ inn-bugs@isc.org -Even if you post to Usenet, please CC the above address. All other INN -mail should go to +(patches are certainly welcome, see below). Even if you post to Usenet, +please CC the above address. All other INN mail should go to inn@isc.org @@ -148,13 +148,18 @@ inn-patches@isc.org +in the body of the message (not as an attachment), or put it on a +webpage and send a link. Patches included with a bug report as +described above should follow the same procedure, but need not be sent +to both addresses (either will do). + Have fun! =head1 Mailing Lists There are various INN-related mailing lists you can join or send messages to if you like. Some of them you must be a member of before you can send -mail to them (thank the Spam gods for that policy), and one of them is +mail to them (thank the spammers for that policy), and one of them is read-only (no postings allowed). =over 24 @@ -286,9 +291,9 @@ Note that INN is supported by the Internet Software Consortium, and although it is free for use and redistribution and incorporation into vendor products and export and anything else you can think of, it costs -money to produce. That money comes from ISP's, hardware and software +money to produce. That money comes from ISPs, hardware and software vendors, companies who make extensive use of the software, and generally -kind hearted folk such as yourself. +kind-hearted folk such as yourself. The Internet Software Consortium has also commissioned a DHCP server implementation, handles the official support/release of BIND, and supports Index: doc/pod/sasl.conf.pod =================================================================== RCS file: /dist1/cvs/isc/inn/inn/doc/pod/sasl.conf.pod,v retrieving revision 1.1 diff -u -r1.1 sasl.conf.pod --- doc/pod/sasl.conf.pod 2000/03/13 13:57:20 1.1 +++ doc/pod/sasl.conf.pod 2002/12/03 04:43:35 @@ -8,7 +8,7 @@ and Security Layer (SASL), defined in RFC 2222, for nnrpd. Now nnrpd implements only Security Layer support, which is an extension of RFC 2595. This means you can get SSL or TLS encrypted NNRP between -your server and newsreaders. It requires OpenSSL 0.9.3 or newer +your server and newsreaders. It requires OpenSSL 0.9.3 or newer from http://www.openssl.org/; it has been tested with versions 0.9.4 and 0.9.5. =head1 INSTALLATION @@ -25,26 +25,22 @@ chown news:news /usr/local/news/lib/cert.pem chmod 640 /usr/local/news/lib/cert.pem -You also can make the keys by the root user as follows. +You also can make the keys as the root user with C. - make cert - =head1 CONFIGURATION Comments begin with a number sign (C<#>) and continue through the end of the line. Blank lines and comments are ignored. -All other lines specify parameters, and should be of the following form: - -Each line of the F in I has the form +All other lines specify parameters, and should be of the form