chiark / gitweb /
docs updates
authorIan Jackson <ian@liberator.relativity.greenend.org.uk>
Mon, 3 May 2010 16:55:08 +0000 (17:55 +0100)
committerIan Jackson <ian@liberator.relativity.greenend.org.uk>
Mon, 3 May 2010 16:55:08 +0000 (17:55 +0100)
backends/innduct.c
doc/man/innduct.8

index 925b7fc..2e375d5 100644 (file)
@@ -379,7 +379,7 @@ static double nocheck_decay= 100; /* conv'd from articles to lambda by main */
 /* all these are initialised to seconds, and converted to periods in main */
 static int reconnect_delay_periods=1000;
 static int flushfail_retry_periods=1000;
-static int backlog_retry_minperiods=50;
+static int backlog_retry_minperiods=100;
 static int backlog_spontrescan_periods=300;
 static int spontaneous_flush_periods=100000;
 static int max_separated_periods=2000;
@@ -3077,7 +3077,9 @@ static void *inndcomm_event(oop_source *lp, int fd, oop_event e, void *u) {
 
       main_input_file= open_input_file(feedfile);
       if (!main_input_file)
-       die("flush succeeded but feedfile %s does not exist!", feedfile);
+       die("flush succeeded but feedfile %s does not exist!"
+           " (this probably means feedfile does not correspond"
+           " to site %s in newsfeeds)", feedfile, sitename);
 
       if (flushing_input_file) {
        SMS(SEPARATED, max_separated_periods, "recovery flush complete");
index f8ecbf0..22799f8 100644 (file)
@@ -11,17 +11,19 @@ innduct \- quickly and reliably stream Usenet articles to remote site
 implements NNTP peer-to-peer news transmission including the streaming
 extensions, for sending news articles to a remote site.  It is
 intended as a replacement for
-.I innfeed
+.B innfeed
 or
-.IR nntpsend
+.BR nntpsend
 and
-.IR innxmit .
+.BR innxmit .
 
 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.
+manages its interaction with
+.BR 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
@@ -39,56 +41,26 @@ innduct daemonises after argument parsing, and all logging (including
 error messages) are sent to syslog (facility
 .BR news ).
 
-The best way to run innduct is probably to periodically invoke innduct
+The best way to run innduct is probably to periodically invoke it
 for each feed (e.g. from cron), passing the
 .B \-q
 option to arrange that innduct silently exits if an instance is
 already running for that site.
-.SH INNDUCT VS INNFEED/NNTPSEND/INNXMIT
-.TP
-.B innfeed
-does roughly the same thing as innduct.  However, the way it receives
-information from innd can result in articles being lost (not offered
-to peers) if innfeed crashes for any reason.  This is an inherent
-defect in the innd channel feed protocol.  innduct uses a file feed,
-constantly "tailing" the feed file, and where implemented uses
-.BR inotify (2)
-to reduce the latency which would come from having to constantly poll
-the feed file.  innfeed is capable of feeding multiple peers from a
-single innfeed instance, whereas each innduct process handles exactly
-one peer.  innduct is much smaller and simpler, at <4kloc to innfeed's
-25kloc.  innfeed needs a separate wrapper script or similar
-infrastructure (of which there is an example in its manpage), whereas
-innduct can be run directly and doesn't need help from shell scripts.
-.TP
-.B nntpsend
-processes feed files in batch mode.  That is, you have to periodically
-invoke nntpsend, and when you do, the feed is flushed and articles
-which arrived before the flush are sent to the peer.  This introduces
-a batching delay, and also means that the NNTP connection to the peer
-needs to be remade at each batch.  nntpsend (which uses innxmit)
-cannot make use of multiple connections to a single peer site.
-However, nntpsend can be left to find automatically which sites need
-feeding by looking in
-.IR pathoutgoing .
-.TP
-.B innxmit
-is the actual NNTP feeder program used by nntpsend.
 .SH GENERAL OPTIONS
 .TP
-.BR \-f | \-\-feedfile= \fIpath\fR
+.BR \-f | \-\-feedfile= \fIDIR\fR / |\fIPATH\fR
 Specifies the
 .I feedfile
 to read, and indirectly specifies the paths to
-be used for various ancillary files (see FILES, below).
-If
-.I path
-ends in a
-.B /
+be used for various associated files (see FILES, below).
+If specified as
+.IB DIR /
 it is taken as a directory to use, and the actual feed file used is
 .IR path / site .
 If
-.I path
+.I PATH
+or
+.I DIR
 does not start with a
 .BR / ,
 it is taken to be relative to
@@ -104,8 +76,8 @@ 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.  A control
-command line is also available on stdin/stdout.
+(including all debug messages) are written to stderr rather than
+syslog.  A control command line is also available on stdin/stdout.
 .TP
 .BI \-\-no-streaming
 Do not try to use the streaming extensions to NNTP (for use eg if the
@@ -128,7 +100,7 @@ Connect to port
 .I PORT
 at the remote site rather than to the NNTP port (119).
 .TP
-.BI \-\-chdir= pathrun
+.BI \-\-chdir= PATHRUN
 Change directory to
 .IR pathrun
 at startup.  The default is
@@ -143,19 +115,94 @@ Listen for control command line connections on
 or
 .I CLI-PATH
 (if it doesn't).  See CONTROLLING INNDUCT, below.
-Note that there is a fairly short limit on the paths to AF_UNIX
-sockets.  If specified as
+Note that there is a fairly short limit on the lengths of AF_UNIX
+socket pathnames.  If specified as
 .IR CLI-DIR \fB/\fR,
 the directory will be created with mode 700 if necessary.
 The default is
 .B innduct/
 which means to create that directory in
-.I pathrun
+.I PATHRUN
 and listen on
-.RB \fIpathrun\fR /innduct/ \fIsite\fR.
+.RB \fIPATHRUN\fR /innduct/ \fIsite\fR.
 .TP
 .BI \-\-help
 Just print a brief usage message and list of the options to stdout.
+.LP
+See TUNING OPTIONS below for more options.
+.SH CONTROLLING INNDUCT
+If you tell innd to drop the feed, innduct will (when it notices,
+which will normally be the next time it decides to flush) finish up the
+articles it has in hand now, and then exit.  It is harmless to cause
+innd to flush the feed (but innduct won't notice and flushing won't
+start a new feedfile; you have to leave that to innduct).
+.LP
+If you want to stop innduct you can send it SIGTERM or SIGINT, or the
+.B stop
+control command, in which case it will report statistics so far and
+quickly exit.  If innduct receives SIGKILL nothing will be broken or
+corrupted; you just won't see some of the article stats.
+.LP
+innduct listens on an AF_UNIX socket (by default,
+.IR pathrun \fB/innduct/\fR site ),
+and provides a command-line interface which can be used to trigger
+various events and for debugging.  When a connection arrives, innduct
+writes a prompt, reads commands a line at a time, and writes any
+output back to the caller.  (Everything uses unix line endings.)  The
+cli can most easily be accessed with a program like
+.I netcat-openbsd
+(eg
+.B nc.openbsd -U
+.RI \fB/var/run/news/innduct/\fR site )
+or
+.IR socat .
+The prompt is
+.IR site \fB|\fR.
+.LP
+The following control commands are supported:
+.TP
+.B h
+Print a list of all the commands understood.  This list includes
+undocumented commands which mess with innduct's internal state and
+should only be used by a developer in conjuction with the innduct
+source code.
+.TP
+.B flush
+Start a new feed file and trigger a flush of the feed.  (Or, cause
+the
+.I FLUSH-FINISH-PERIOD
+to expire early, forcibly completing a previously started flush.)
+.TP
+.B stop
+Log statistics and exit.  (Same effect as SIGTERM or SIGINT.)
+.TP
+.BR "dump q" | a
+Writes information about innduct's state to a plain text file
+.IR feedfile \fB_dump\fR.
+This overwrites any previous dump.  innduct does not ever delete these
+dump files.
+.B "dump q"
+gives a summary including general state and a list of connections;
+.B "dump a"
+also includes information about each article innduct is dealing with.
+.TP
+.B next blscan
+Requests that innduct rescan for new backlog files at the next
+.I PERIOD
+poll.  Normally innduct assumes that any backlog files dropped in by
+the administrator are not urgent, and it may not get around to
+noticing them for
+.IR BACKLOG-SCAN-PERIOD .
+.TP
+.B next conn
+Resets the connection startup delay counter so that innduct may
+consider making a new connection to the peer right away, regardless
+of the setting of
+.IR RECONNECT-PERIOD .
+A connection attempt will still only be made if innduct feels that it
+needs one, and innduct may wait up to
+.I PERIOD
+before actually starting the attempt.
 .SH TUNING OPTIONS
 You should not normally need to adjust these.  Time intervals may
 specified in seconds, or as a number followed by one of the following
@@ -165,12 +212,14 @@ units:
 .BR "das hs ks Ms" .
 .TP
 .BI \-\-max-connections= max
-Restricts the maximum number of simultaneous NNTP connections used by
-for each site to
+Restricts the maximum number of simultaneous NNTP connections
+per peer to
 .IR max .
+There is no global limit on the number of connections used by all
+innducts, as the instances for different sites are entirely
+independent.
 The default is
 .BR 10 .
-There is no global limit on the number of connections.
 .TP
 .BI \-\-max-queue-per-conn= per-conn-max
 Restricts the maximum number of outstanding articles queued on any
@@ -184,15 +233,16 @@ The default is
 Restricts the maximum number articles read into core from any one
 input file to
 .IR max .
-The default is twice the value of per-conn-max.
+The default is
+.B twice
+.IR per-conn-max .
 .TP
 .BI \-\-feedfile-flush-size= bytes
 Specifies that innduct should flush the feed and start a new feedfile
 when the existing 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
+batchfiles growing much beyond this size.  The default is
 .BR 100000 .
 .TP
 .BI \-\-period-interval= PERIOD-INTERVAL
@@ -263,7 +313,7 @@ offered to it by another of its peers, and that we should try again,
 we wait at least
 .IR PERIOD .
 before offering the article again.  The default is
-.BR 50s .
+.BR 100s .
 .TP
 .BI \-\-backlog-rescan-interval= BACKLOG-SCAN-PERIOD
 We scan the directory containing
@@ -273,14 +323,7 @@ for backlog files at least every
 in case the administrator has manually dropped in a file there for
 processing.
 The default is
-.TP
-.BI \-\-max-flush-interval= PERIOD
-We flush the feed at least every
-.IR PERIOD
-even if the current instance of the feedfile has not reached the size
-threshold.
-The default is
-.BR 100000s .
+.BR 300s .
 .TP
 .BI \-\-max-flush-interval= PERIOD
 We flush the feed and start a new feedfile at least every
@@ -295,11 +338,10 @@ If we flushed
 .IR FLUSH-FINISH-PERIOD
 ago, and are still trying to finish processing articles that were
 written to the old feed file, we forcibly and violently make sure that
-we do by abandoning and deferring all the work (which includes
-unceremoniously dropping any connections on which we've sent some of
-those articles but not yet had replies, as they're probably stuck
-somehow).
-The default is
+we can finish the old feed file: we abandon and defer all the work,
+which includes unceremoniously dropping any connections on which
+we've sent some of those articles but not yet had replies, as they're
+probably stuck somehow.  The default is
 .BR 2000s .
 .TP
 .BI \-\-idle-timeout= PERIOD
@@ -319,8 +361,9 @@ but if there are too many we conclude that the corruption to our
 on-disk data is too severe, and crash; to successfully restart,
 administrator intervention will be required.  This avoids flooding the
 logs with warnings and also arranges to abort earlyish if an attempt
-is made to process a file in the wrong format.
-The default is
+is made to process a file in the wrong format.  We need to tolerate a
+small proportion of broken lines, if for no other reason than that a
+crash might leave a half-blanked-out entry.  The default is
 .BR 1
 (ie, 1%).
 .TP
@@ -334,78 +377,39 @@ The default is
 filled with random data, or one corrupt 1024-byte disk block filled
 with an inappropriate text file with a mean line length of at least
 35).
-.SH CONTROLLING INNDUCT
-If you tell innd to drop the feed, innduct will (when it notices,
-which will normally be the next time it decides flushes) finish up the
-articles it has in hand now, and then exit.  It is harmless to cause
-innd to flush the feed (but innduct won't notice and flushing won't
-start a new feedfile; you have to leave that to innduct).
-.LP
-If you want to stop innduct you can send it SIGTERM or SIGINT, or the
-.B stop
-control command, in which case it will report statistics so far and
-quickly exit.  If innduct receives SIGKILL nothing will be broken or
-corrupted; you just won't see some of the article stats.
-.LP
-innduct listens on an AF_UNIX socket, and provides a command-line
-interface which can be used to trigger various events and for
-debugging.  innduct listens (by default on
-.IR pathrun \fB/innduct/\fR site )
-and when connected reads and writes lines (with unix line endings).
-The cli can most easily be accessed with a program like
-.I netcat-openbsd
-(eg
-.B nc.openbsd -U /var/run/news/innduct/
-.IR site )
-or
-.IR socat .
-The prompt is
-.IR site \fB|\fR.
-.LP
-The following control commands are supported:
-.TP
-.B h
-Print a list of all the commands understood.  This list includes
-undocumented commands which mess with innduct's internal state and
-should only be used by a developer in conjuction with the innduct
-source code.
-.TP
-.B flush
-Start a new feed file and trigger a flush of the feed.  (Or, cause
-the
-.I FLUSH-FINISH-PERIOD
-to expire early, forcibly completing a previously started flush.)
-.TP
-.B stop
-Log statistics and exit.  (Same effect as SIGTERM or SIGINT.)
+.SH INNDUCT VS INNFEED/NNTPSEND/INNXMIT
 .TP
-.BR "dump q" | a
-Writes information about innduct's state to a plain text file
-.IR feedfile \fB_dump\fR.
-This overwrites any previous dump.
-.B "dump q"
-is a summary including general state and a list of connections;
-.B "dump a"
-also includes information about each article innduct is dealing with.
+.B innfeed
+does roughly the same thing as innduct.  However, the way it receives
+information from innd can result in articles being lost (not offered
+to peers) if innfeed crashes for any reason.  This is an inherent
+defect in the innd channel feed protocol.  innduct uses a file feed,
+constantly "tailing" the feed file, and where implemented uses
+.BR inotify (2)
+to reduce the latency which would come from having to constantly poll
+the feed file.  innduct is much smaller and simpler, at <4kloc to
+innfeed's 25kloc.  innfeed needs a separate helper script or similar
+infrastructure (of which there is an example in its manpage), whereas
+innduct can be run directly and doesn't need help from shell scripts.
+However, innfeed is capable of feeding multiple peers from a single
+innfeed instance, whereas each innduct process handles exactly one
+peer.
 .TP
-.B next blscan
-Requests that innduct rescan for new backlog files at the next
-.I PERIOD
-poll.  Normally innduct assumes that any backlog files dropped in by
-the administrator are not urgent and may not get around to noticing
-them for
-.IR BACKLOG-SCAN-PERIOD .
+.B nntpsend
+processes feed files in batch mode.  That is, you have to periodically
+invoke nntpsend, and when you do, the feed is flushed and articles
+which arrived before the flush are sent to the peer.  This introduces
+a batching delay, and also means that the NNTP connection to the peer
+needs to be remade at each batch.  nntpsend (which uses innxmit)
+cannot make use of multiple connections to a single peer site.
+However, nntpsend automatically find which sites need feeding by
+looking in
+.IR pathoutgoing ,
+whereas the administrator needs to arrange to invoke innduct
+separately for each peer.
 .TP
-.B next conn
-Resets the connection startup delay counter so that innduct may
-consider making a new connection to the peer right away, regardless
-of the setting of
-.IR RECONNECT-PERIOD .
-A connection attempt will still only be made if innduct feels that it
-needs one, and innduct may wait up to
-.I PERIOD
-before actually starting the attempt.
-.IR BACKLOG-SCAN-PERIOD .
+.B innxmit
+is the actual NNTP feeder program used by nntpsend.
 .SH EXIT STATUS
 .TP
 .B 0
@@ -455,7 +459,7 @@ explained here:
 .IP \fIpathrun\fR
 .IX Item "default directory"
 Default current working directory for innduct, and also default
-parent directory for the command line socket.
+grandparent directory for the command line socket.
 .IP \fIpathoutgoing\fR/\fIsite\fR
 .IX Item "default feedfile"
 Default
@@ -470,9 +474,10 @@ is of the form
 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.
+correspond to articles it has processed: each such line is replaced
+with one containing only spaces.  Only innd should create
+.IR feedfile ,
+and only innduct should remove it.
 .IP \fIfeedfile\fR_lock
 .IX Item "lock file"
 Lockfile, preventing multiple innduct invocations for the same
@@ -493,30 +498,33 @@ troubleshooting.
 .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.
+before it asks inn to flush the feed.  Only innduct should create,
+modify or remove this file.
 .IP \fIfeedfile\fR_defer
 .IX Item "flushing file"
-Batch file containing details of articles whose transmission has
+Batch file containing details of articles whose transmission has very
 recently been deferred at the request of the recipient site.  Created,
-written, read and removed by innduct.
+written, read and removed (only) 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 you
-(the administrator) may also safely remove backlog files.
+by innduct, and will also be read, updated and removed by innduct.
+However you (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.  Be sure to have finished writing the file before
-you rename it to match the pattern \fIfeedfile\fR\fB_backlog\fR*, as
-otherwise innduct may find and process the file and read it to EOF
-before you have finished creating it.
+process it (including blanking out entries for processed articles) and
+eventually remove it.  \fIsomething\fR may not contain \fB#\fR \fB~\fR
+or \fB/\fR.
+.IP
+Be sure to have finished writing the file before you rename it to
+match the pattern \fIfeedfile\fR\fB_backlog\fR*, as otherwise innduct
+may find and process the file, and even think it has finished it,
+before you have written the complete file.  You may also safely remove
+backlog files.
 .IP \fIpathrun\fR\fB/innduct/\fB\fIsite\fR
 .IX Item "control command line socket"
 Default AF_UNIX listening socket for the control command line.  See
@@ -534,6 +542,8 @@ Used for
 and associated paths),
 .IR pathrun
 (to compute default
+.IR PATHRUN
+and hence effective default
 .IR CLI-DIR
 and
 .IR CLI-PATH ),
@@ -545,4 +555,5 @@ and/or
 Written by Ian Jackson <ijackson@chiark.greenend.org.uk>
 .SH "SEE ALSO"
 inn.conf(5),
+innd(8),
 newsfeeds(5)