From c48917ea3acd06da8ce73a9894a092cd495303d9 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Wed, 21 Apr 2010 18:37:08 +0100 Subject: [PATCH 1/1] wip manpage --- doc/man/innduct.8 | 275 +++++++++++++++------------------------------- 1 file changed, 86 insertions(+), 189 deletions(-) diff --git a/doc/man/innduct.8 b/doc/man/innduct.8 index 87c602a..5e29828 100644 --- a/doc/man/innduct.8 +++ b/doc/man/innduct.8 @@ -5,201 +5,98 @@ innduct \- quickly and reliably stream Usenet articles to remote site .B innduct .RI [ options ] [ -.I sitename +.I site +[ .I fqdn -] +]] .SH DESCRIPTION -.I Innduct -is a +.B innduct +implements NNTP peer-to-peer news transmission including the streaming +extensions, for sending news articles to a remote site. -front-end that invokes -.IR innxmit (1) -to send Usenet articles to a remote NNTP site. -.PP -The sites to be fed may be specified by giving -.I sitename -.I fqdn -pairs on the command line. -If no such pairs are given, -.I innduct -defaults to the information given in the -.I innduct.ctl -config file. -.PP -The -.I sitename -should be the name of the site as specified in the -.IR newsfeeds (5) -file. -The -.I fqdn -should be the hostname or IP address of the remote site. -.PP -An -.I innxmit -is launched for sites with queued news. -All -.I innxmit -processes are spawned in the background and the script waits for -them all to finish before returning. -Output is sent to the file -.IR /innduct.log . -In order to keep from overwhelming the local system, -.I innduct -waits five seconds before spawning each child. -.PP -.I Innduct -expects that the batchfile for a site is named -.IR /sitename . -To prevent batchfile corruption, -.IR shlock (1) -is used to ``lock'' these files. -.PP -When -.I sitename +One instance of innduct is run for each peer site. innduct manages +its interaction with innd so that articles are transmitted quickly, +and manages the retransmission its own backlog. innduct includes the +locking necessary to avoid multiple simutaneous invocations. + +By default, innduct reads the default feed file name corresponding to +the site +.I site +(as specified in +.IR newsfeeds (5)) +and feeds it vian NNTP, streaming if possible, to the host +.IR fqdn . + +If .I fqdn -pairs are given on the command line, -any flags given on the command completely describe how -.I innxmit -and -.I shrinkfile -operate. -When no such pairs are given on the command line, then -the information found in -.I innduct.ctl -becomes the default flags for that site. -Any flags given on the command line override the default flags -for the site. +is not specified, it defaults to +.IR site . + +Logging is sent to syslog. .SH OPTIONS .TP -.B "\-d \-D" -The ``\-d'' flag causes -.I innduct -to send output to stdout rather than the log file -.IR /innduct.log . -The ``\-D'' flag does the same -and it passes ``\-d'' to all -.I innxmit -invocations, which in turn causes -.I innxmit -to go into debug mode. -.TP -.B -n -If the ``\-n'' flag is used, then -.I innduct -does not use -.IR shlock (1) -and does not lock batch files. -.TP -.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 delay -If the ``\-w'' flag is used, then -.I innduct -waits for -.I delay -seconds after flushing the site before launching -.IR innxmit . -.TP -.B "\-a \-c \-l \-N \-P \-p \-r \-S \-T \-t" -The ``\fB\-a\fP'', ``\fB\-c\fP'', ``\fB\-l\fP'', ``\fB\-P\fP'', ``\fB\-p\fP'', -``\fB\-r\fP'', \``\fB\-S\fP'', ``\fB\-T\fP'' and ``\fB\-t\fP'' -flags are passed on to the child -.I innxmit -program. The ``\-N'' flag is passed as ``\fB\-s\fP'' flag to the child -.I innxmit -program. -See -.IR innxmit (8) -for more details. -Note that if the ``\-p'' flag is used then no connection is made and -no articles are fed to the remote site. -It is useful to have -.IR cron (8) -invoke -.I innduct -with this flag in case a site cannot be reached for an extended period of time. -.SH EXAMPLES -With the following -.IR innduct.ctl (5) -control file: -.PP -.RS -.nf -nsavax:erehwon.nsavax.gov::-S -t60 -group70:group70.org:: -walldrug:walldrug.com:4m-1m:-T1800 -t300 -kremvax:kremvax.cis:2m: -.fi -.RE -.PP -The command: -.PP -.RS -innduct -.PP -.RE -will result in the following: -.PP -.RS -.nf -Sitename Truncation Innxmit flags -nsavax (none) \-a \-S \-t60 -group70 (none) \-a \-t180 -walldrug 1m if >4m \-a \-T1800 \-t300 -kremvax 2m \-a \-t180 -.fi -.RE -.PP -The command: -.PP -.RS -innduct \-d \-T1200 -.RE -.PP -will result in the following: -.PP -.RS -.nf -Sitename Truncation Innxmit flags -nsavax (none) \-a \-d \-S \-T1200 \-t60 -group70 (none) \-a \-d \-T1200 \-t180 -walldrug 1m if >4m \-a \-d \-T1200 \-t300 -kremvax 2m \-a \-d \-T1200 \-t180 -.fi -.RE -.PP -The command: -.PP -.RS -innduct \-s 5m \-T1200 nsavax erehwon.nsavax.gov group70 group70.org -.PP -.RE -will result in the following: -.PP -.RS -.nf -Sitename Truncation Innxmit flags -nsavax 5m \-a \-T1200 \-t180 -group70 5m \-a \-T1200 \-t180 -.fi -.RE -.PP -Remember that ``\-a'' is always given, and ``\-t'' defaults to 180. +.B \-h fqdn +Specifies the domain name of the host to connect to via NNTP. The +default is the site name. The domain name may be specified with +.B \-h +or as a 2nd non-option argument, but not both. +.SH FILES +.IX Header "FILES" +.IP \fIpathoutgoing\fR/\fIsite\fR +.IX Item "default feedfile" +Default +.IR feedfile . +.IP \fIfeedfile\fR +.IX Item feedfile +Main feed file as specified in +.IR newsfeeds (5). +This and other batchfiles used by innduct contains lines each of which +is of the form +\& \fItoken\fR \fImessageid\fR +where \fItoken\fR is the inn storage API token. Such lines can be +written by \fBTf,Wnm\fR in a \fInewsfeeds\fR(5) entry. During +processing, innduct overwrites lines in the batch files which +correspond to articles it has processed: the line is replaced with +one containing only spaces. Only innd should create this file, and +only innduct should remove it. +.IP \fIfeedfile\fR_lock +.IX Item "lock file" +Lockfile, preventing multiple innduct invocations for the same +feed. A process holds this lock after it has opened the lockfile, +made an fcntl F_SETLK call, and then checked with stat and fstat that +the file it now has open and has locked still has the name +\fIfeedfile\fR_lock. (Only) the lockholder may delete the lockfile. +.IP \fIfeedfile\fR_flushing +.IX Item "flushing file" +Batch file: the main feedfile is renamed to this filename by innduct +before it asks inn to flush the feed. Only innduct should create or +remove this file. +.IP \fIfeedfile\fR_defer +.IX Item "flushing file" +Batch file containing details of articles whose transmission has +recently been deferred at the request of the recipient site. Created, +written, read and removed by innduct. +.IP \fIfeedfile\fR_defer +.IX Item "defer file" +Batch file containing details of articles whose transmission has +recently been deferred at the request of the recipient site. Created, +written, read and removed by innduct. +.IP \fIfeedfile\fR_backlog.\fItime_t\fR.\fIinum\fR +.IX Item "backlog file" +Batch file containing details of articles whose transmission has less +recently been deferred at the request of the recipient site. Created +by innduct, and will also be read and removed by innduct. However the +administrator may also safely remove backlog files. +.IP \fIfeedfile\fR_backlog\fIsomething\fR +.IX Item "manual backlog file" +Batch file manually provided by the administrator. The file should be +complete and ready to process at the time it is renamed or hardlinked +to this name. innduct will then automatically find and read and +process it and eventually remove it. The administrator may also +safely remove backlog files. \fIsomething\fR should not contain +\fB#\fR or \fB~\fR. .SH HISTORY -Written by Landon Curt Noll -and Rich $alz for InterNetNews. -.de R$ -This is revision \\$3, dated \\$4. -.. -.R$ $Id: innduct.8 5909 2002-12-03 05:17:18Z vinocur $ +Written by Ian Jackson .SH "SEE ALSO" inn.conf(5), -innxmit(1), -newsfeeds(5), -innduct.ctl(5), -shrinkfile(1). +newsfeeds(5) -- 2.30.2