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.
Do not try to use the streaming extensions to NNTP (for use eg if the
peer can't cope when we send MODE STREAM).
.TP
+.BI \-\-no-filemon
+Do not try to use the file change monitoring support to watch for
+writes by innd to the feed file; poll it instead. (If file monitoring
+is not compiled in, this option just downgrades the log message which
+warns about this situation.)
+.TP
.BR \-C | \-\-inndconf= \fIFILE\fR
Read
.I FILE
instead of the default
.BR inn.conf .
.TP
+.BR \-\-cli= \fIDIR\fR / |\fIPATH\fR
+Bind the control command line socket to
+.IB DIR / site _cli
+(if the value ends with a
+.BR /)
+or
+.I PATH
+(if it doesn't). See CONTROLLING INNDUCT, below.
+This option may be essential, if the
+path to
+.I feedfile
+is too long, as there is a fairly short limit on the paths to AF_UNIX
+sockets. The default is
+.IR feedfile \fB_cli\fR.
+.TP
.BI \-\-port= PORT
Connect to port
.I PORT
.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
.TP
.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
+innduct wakes up every
+.I PERIOD-INTERVAL
+to do various housekeeping checks. Also, many of the timeout and
+rescan intervals (those specified in this manual as
+.IR PERIOD )
+are rounded up to the next multiple of
+.IR PERIOD-INTERVAL .
.TP
.BI \-\-connection-timeout= TIME
How long to allow for a connection setup attempt before giving up.
up. The default is
.BR 100s .
.TP
+.BI \-\-feedfile-poll= TIME
+How often to poll the feedfile for new articles written by innd
+if file monitoring
+.RI ( inotify
+or equivalent) is not available. (When file monitoring is available,
+there is no need for periodic checks and we wake immediately up
+whenever the feedfile changes.)
+The default is
+.BR 5s .
+.TP
.BI \-\-no-check-proportion= PERCENT
If the moving average of the proportion of articles being accepted
(rather than declined) by the peer exceeds this value, innduct uses
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
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
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
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. The socket is called
+.IB feedfile _cli
+and when connected reads and writes lines (with unix line endings).
+It can most easily be accessed with a program like
+.I netcat-openbsd
+(eg
+.B nc.openbsd -U
+.IR feedfile \fB_cli\fR)
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
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 \fIpathoutgoing\fR/\fIsite\fR
.IX Item "default feedfile"
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 \fIfeedfile\fR_cli
+.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
.IR pathoutgoing
-if none is specified, and also for
+if none is specified, for finding how to communicate with innd,
+and also for
.IR sourceaddress
and/or
.IR sourceaddress6 .
~ian / inn-innduct.git / blobdiff