X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=inn-innduct.git;a=blobdiff_plain;f=doc%2Fman%2Finnduct.8;h=b71c2f8cb6a634a8f23950769cb9ac669b79084b;hp=87c602ad0ffa2a165a2fec7d33e9a2ad736bc9c1;hb=fc66b511debe93980fd49331d96939fb876024da;hpb=8b12e9db444d3a0f66ae0f2422d082cec186f9b9 diff --git a/doc/man/innduct.8 b/doc/man/innduct.8 index 87c602a..b71c2f8 100644 --- a/doc/man/innduct.8 +++ b/doc/man/innduct.8 @@ -4,202 +4,170 @@ innduct \- quickly and reliably stream Usenet articles to remote site .SH SYNOPSIS .B innduct .RI [ options ] -[ -.I sitename -.I fqdn -] +.I site +.RI [ 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 +You need to run one instance of innduct for each peer site. innduct +manages its interaction with innd, including flushing the feed as +appropriate, etc., so that articles are transmitted quickly, and +manages the retransmission of its own backlog. innduct includes the +locking necessary to avoid multiple simutaneous invocations. + +By default, innduct reads the default feedfile corresponding to +the site +.I site +(is +.IR pathoutgoing / site ) +and feeds it via 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. -.SH OPTIONS +is not specified, it defaults to +.IR site . + +Logging is sent to syslog. +.SH GENERAL OPTIONS +.TP +.BR \-f | \-\-feedfile= \fIfeedfile\fR +Specifies +.IR feedfile . +If the specified value ends in a +.B / +it is taken as a directory to use as if it were +.I pathoutgoing +and the actual feed file used is +.IR specified_feedfile / site . +.TP +.BR \-q | \-\-quiet-multiple +Makes innduct silently exit (with status 0) if another innduct holds +the lock for the site. Without \fB-q\fR, this causes a fatal error to +be logged and a nonzero exit. +.TP +.BR \-\-no-daemon +Do not daemonise. innduct runs in the foreground and all messages +(including all debug messages) are written to stderr. +.TP +.BI \-\-no-streaming +Do not try to use the streaming extensions to NNTP (eg if the peer +can't cope when we send MODE STREAM). +.TP +.BI \-\-inndconf= FILE +Read +.I FILE +instead of the default +.BR inn.conf . +This is currently only used if +.BI \-f feedfile +is not specified, to find the value +.I pathoutgoing +for constructing the feedfile name from the site name. +.TP +.BI \-\-port= PORT +Connect to port +.I PORT +at the remote site rather than to the NNTP port (119). .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. +.BI \-\-help +Just print a brief usage message and list of the options to stdout. +.SH TUNING OPTIONS +You should not normally need to adjust these. .TP -.B -n -If the ``\-n'' flag is used, then -.I innduct -does not use -.IR shlock (1) -and does not lock batch files. +.BI \-\-max-connections= max +Restricts the maximum number of simultaneous NNTP connections used by +for each site to +.IR max . +The default is 10. There is no global limit on the number of +connections. .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. +.BI \-\-max-queue-per-conn= max +Restricts the maximum number of outstanding articles queued on any +particular connection +.IR max . +The default is 200. (Non-streaming connections can only handle one +article at a time.) .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 . +.BI \-\-feedfile-flush-size= bytes +Specifies that innduct should flush when the feedfile size exceeds +.IR bytes ; +the effect is that the innduct will try to avoid the various +batchfiles growing much beyond this size while the link to the peer is +working. The default is 100,000 bytes. .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. +.BI \-\-period-interval= PERIOD-INTERVAL +Specifies wakup interval and period granularity. +innduct wakes up every PERIOD-INTERVAL to do various housekeeping +checks. Also, many of the timeout and rescan intervals (those +specified in this manual as +.IR PERIOD s) +are rounded up to the next multiple of PERIOD-INTERVAL. +The default is one minute. +.SH EXIT STATUS +0 ok +4 one is already running +8 bad usage +12 trouble +.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_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 may not contain +\fB#\fR \fB~\fR or \fB/\fR. +.IP /etc/news/inn.conf +.IX Item inn.conf +Used to find +.IR pathoutgoing +if none is specified. .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)