chiark / gitweb /
Merge branch 'master' of login.chiark.greenend.org.uk:public-git/inn-innduct
[inn-innduct.git] / doc / man / innduct.8
index 83aeade..f8ecbf0 100644 (file)
@@ -9,7 +9,13 @@ innduct \- quickly and reliably stream Usenet articles to remote site
 .SH DESCRIPTION
 .B innduct
 implements NNTP peer-to-peer news transmission including the streaming
-extensions, for sending news articles to a remote site.
+extensions, for sending news articles to a remote site.  It is
+intended as a replacement for
+.I innfeed
+or
+.IR nntpsend
+and
+.IR innxmit .
 
 You need to run one instance of innduct for each peer site.  innduct
 manages its interaction with innd, including flushing the feed as
@@ -20,11 +26,10 @@ locking necessary to avoid multiple simutaneous invocations.
 By default, innduct reads the default feedfile corresponding to
 the site
 .I site
-(is
+(ie
 .IR pathoutgoing / site )
 and feeds it via NNTP, streaming if possible, to the host
 .IR fqdn .
-
 If
 .I fqdn
 is not specified, it defaults to
@@ -35,10 +40,10 @@ error messages) are sent to syslog (facility
 .BR news ).
 
 The best way to run innduct is probably to periodically invoke innduct
-for each feed (e.g. from cron), passing innduct it the
+for each feed (e.g. from cron), passing the
 .B \-q
-option to arrange that it silently exits if an innduct is already
-running for that site.
+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
@@ -51,7 +56,7 @@ constantly "tailing" the feed file, and where implemented uses
 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 3kloc to innfeed's
+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.
@@ -71,15 +76,26 @@ feeding by looking in
 is the actual NNTP feeder program used by nntpsend.
 .SH GENERAL OPTIONS
 .TP
-.BR \-f | \-\-feedfile= \fIfeedfile\fR
-Specifies
-.IR feedfile .
-If the specified value ends in a
+.BR \-f | \-\-feedfile= \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 /
-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 .
+it is taken as a directory to use, and the actual feed file used is
+.IR path / site .
+If
+.I path
+does not start with a
+.BR / ,
+it is taken to be relative to
+.IR pathoutgoing
+from inn.conf.
+The default is
+.IR site .
 .TP
 .BR \-q | \-\-quiet-multiple
 Makes innduct silently exit (with status 0) if another innduct holds
@@ -88,7 +104,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.
+(including all debug messages) are written to stderr.  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
@@ -106,31 +123,37 @@ Read
 instead of the default
 .BR inn.conf .
 .TP
-.BI \-\-ctrl-sock-dir= DIR
-Bind the real control socket to a unique filename in
-.IR DIR .
-A symlink will be made pointing to the actual file used, named
-.IB feedfile _control
-in the same directory as
-.IR feedfile ,
-but since
-.IR feedfile 's
-path may be too long for an AF_UNIX socket path, innduct always
-creates the sockets in this dedicated directory which is expected to
-have a short path.  If
-.I DIR
-does not exist it will be created with mode 0700; if it does
-exist it must not be a symlink and must be owned by the user running
-innduct and have no access for "other".  If the control socket cannot
-be set up (for this or any other reason), a warning is logged, but
-such situations are not fatal for innduct's startup.  The default is
-.BR /tmp/innduct.control .
-.TP
 .BI \-\-port= PORT
 Connect to port
 .I PORT
 at the remote site rather than to the NNTP port (119).
 .TP
+.BI \-\-chdir= pathrun
+Change directory to
+.IR pathrun
+at startup.  The default is
+.I pathrun
+from inn.conf.
+.TP
+.BR \-\-cli= \fICLI-DIR\fR / |\fICLI-PATH\fR| none
+Listen for control command line connections on
+.IB CLI-DIR / site
+(if the value ends with a
+.BR /)
+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
+.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
+and listen on
+.RB \fIpathrun\fR /innduct/ \fIsite\fR.
+.TP
 .BI \-\-help
 Just print a brief usage message and list of the options to stdout.
 .SH TUNING OPTIONS
@@ -149,14 +172,20 @@ The default is
 .BR 10 .
 There is no global limit on the number of connections.
 .TP
-.BI \-\-max-queue-per-conn= max
+.BI \-\-max-queue-per-conn= per-conn-max
 Restricts the maximum number of outstanding articles queued on any
-particular connection
+particular connection to
 .IR max .
 (Non-streaming connections can only handle one article at a time.)
 The default is
 .BR 200 .
 .TP
+.BI \-\-max-queue-per-file= max
+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.
+.TP
 .BI \-\-feedfile-flush-size= bytes
 Specifies that innduct should flush the feed and start a new feedfile
 when the existing feedfile size exceeds
@@ -212,9 +241,9 @@ half-life of
 The default is
 .BR 100 .
 .TP
-.BI \-\-reconnect-interval= PERIOD
+.BI \-\-reconnect-interval= RECONNECT-PERIOD
 Limits initiation of new connections to one each
-.IR PERIOD .
+.IR RECONNECT-PERIOD .
 This applies to reconnections if the peer has been down, and also to
 ramping up the number of connections we are using after startup or in
 response to an article flood.  The default is
@@ -236,11 +265,11 @@ we wait at least
 before offering the article again.  The default is
 .BR 50s .
 .TP
-.BI \-\-backlog-rescan-interval= PERIOD
+.BI \-\-backlog-rescan-interval= BACKLOG-SCAN-PERIOD
 We scan the directory containing
 .I feedfile
 for backlog files at least every
-.IR PERIOD ,
+.IR BACKLOG-SCAN-PERIOD ,
 in case the administrator has manually dropped in a file there for
 processing.
 The default is
@@ -261,6 +290,18 @@ threshold.
 The default is
 .BR 100000s .
 .TP
+.BI \-\-flush-finish-timeout= FLUSH-FINISH-PERIOD
+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
+.BR 2000s .
+.TP
 .BI \-\-idle-timeout= PERIOD
 Connections which have had no activity for
 .IR PERIOD
@@ -293,27 +334,78 @@ 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 INTERACTING WITH INNDUCT
-innduct dances a somewhat complicated dance with innd to make sure
-that everything goes smoothly and that there are no races.  (See the
-two ascii-art diagrams in innduct.c for details of the protocol.)  Do
-not mess with the feedfile and other associated files, other than as
-explained below in the section
-.BR FILES .
-.LP
+.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
-There are no signals that can usefully be sent to innduct to give it
-complicated instructions.  If you need to kill innduct, feel free to
-send it a
-.B SIGTERM
+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
-.B SIGKILL
-and nothing will be broken or corrupted.
+.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.
+.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.
+.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 .
+.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 .
 .SH EXIT STATUS
 .TP
 .B 0
@@ -354,7 +446,16 @@ These exit statuses are used by children forked by innduct to
 communicate to the parent.  You should not see them.  If you do, it is
 a bug.
 .SH FILES
+innduct dances a somewhat complicated dance with innd to make sure
+that everything goes smoothly and that there are no races.  (See the
+two ascii-art diagrams in innduct.c for details of the protocol.)  Do
+not mess with the feedfile and other associated files, other than as
+explained here:
 .IX Header "FILES"
+.IP \fIpathrun\fR
+.IX Item "default directory"
+Default current working directory for innduct, and also default
+parent directory for the command line socket.
 .IP \fIpathoutgoing\fR/\fIsite\fR
 .IX Item "default feedfile"
 Default
@@ -416,12 +517,27 @@ safely remove backlog files.  \fIsomething\fR may not contain \fB#\fR
 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.
+.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
+CONTROLLING INNDUCT, above.
+.IP \fIfeedfile\fR_dump
+.IX Item "debug dump file"
+On request via a control connection innduct dumps a summary of its
+state to this text file.  This is mostly useful for debugging.
 .IP /etc/news/inn.conf
 .IX Item inn.conf
-Used to find
+Used for
 .IR pathoutgoing
-if none is specified, for finding how to communicate with innd,
-and also for
+(to compute default
+.IR feedfile
+and associated paths),
+.IR pathrun
+(to compute default
+.IR CLI-DIR
+and
+.IR CLI-PATH ),
+for finding how to communicate with innd, and also for
 .IR sourceaddress
 and/or
 .IR sourceaddress6 .