4 innduct \- quickly and reliably stream Usenet articles to remote site
12 implements NNTP peer-to-peer news transmission including the streaming
13 extensions, for sending news articles to a remote site. It is
14 intended as a replacement for
21 You need to run one instance of innduct for each peer site. innduct
22 manages its interaction with
24 including flushing the feed as appropriate, etc., so that articles are
25 transmitted quickly, and manages the retransmission of its own
26 backlog. innduct includes the locking necessary to avoid multiple
27 simutaneous invocations.
29 By default, innduct reads the default feedfile corresponding to
33 .IR pathoutgoing / site )
34 and feeds it via NNTP, streaming if possible, to the host
38 is not specified, it defaults to
41 innduct daemonises after argument parsing, and all logging (including
42 error messages) are sent to syslog (facility
45 The best way to run innduct is probably to periodically invoke it
46 for each feed (e.g. from cron), passing the
48 option to arrange that innduct silently exits if an instance is
49 already running for that site.
52 .BR \-f | \-\-feedfile= \fIDIR\fR / |\fIPATH\fR
55 to read, and indirectly specifies the paths to
56 be used for various associated files (see FILES, below).
59 it is taken as a directory to use, and the actual feed file used is
67 it is taken to be relative to
73 .BR \-q | \-\-quiet-multiple
74 Makes innduct silently exit (with status 0) if another innduct holds
75 the lock for the site. Without \fB-q\fR, this causes a fatal error to
76 be logged and a nonzero exit.
79 Do not daemonise. innduct runs in the foreground, but otherwise
80 operates normally (logging to syslog, etc.).
83 Do not daemonise. innduct runs in the foreground and all messages
84 (including all debug messages) are written to stderr rather than
85 syslog. A control command line is also available on stdin/stdout.
88 Do not try to use the streaming extensions to NNTP (for use eg if the
89 peer can't cope when we send MODE STREAM).
92 Do not try to use the file change monitoring support to watch for
93 writes by innd to the feed file; poll it instead. (If file monitoring
94 is not compiled in, this option just downgrades the log message which
95 warns about this situation.)
97 .BR \-C | \-\-inndconf= \fIFILE\fR
100 instead of the default
106 at the remote site rather than to the NNTP port (119).
108 .BI \-\-chdir= PATHRUN
111 at startup. The default is
115 .BR \-\-cli= \fICLI-DIR\fR / |\fICLI-PATH\fR| none
116 Listen for control command line connections on
118 (if the value ends with a
122 (if it doesn't). See CONTROLLING INNDUCT, below.
123 Note that there is a fairly short limit on the lengths of AF_UNIX
124 socket pathnames. If specified as
126 the directory will be created with mode 700 if necessary.
129 which means to create that directory in
132 .RB \fIPATHRUN\fR /innduct/ \fIsite\fR.
135 Just print a brief usage message and list of the options to stdout.
137 See TUNING OPTIONS below for more options.
138 .SH CONTROLLING INNDUCT
139 If you tell innd to drop the feed, innduct will (when it notices,
140 which will normally be the next time it decides to flush) finish up the
141 articles it has in hand now, and then exit. It is harmless to cause
142 innd to flush the feed (but innduct won't notice and flushing won't
143 start a new feedfile; you have to leave that to innduct).
145 If you want to stop innduct you can send it SIGTERM or SIGINT, or the
147 control command, in which case it will report statistics so far and
148 quickly exit. If innduct receives SIGKILL nothing will be broken or
149 corrupted; you just won't see some of the article stats.
151 innduct listens on an AF_UNIX socket (by default,
152 .IR pathrun \fB/innduct/\fR site ),
153 and provides a command-line interface which can be used to trigger
154 various events and for debugging. When a connection arrives, innduct
155 writes a prompt, reads commands a line at a time, and writes any
156 output back to the caller. (Everything uses unix line endings.) The
157 cli can most easily be accessed with a program like
161 .RI \fB/var/run/news/innduct/\fR site )
167 The following control commands are supported:
170 Print a list of all the commands understood. This list includes
171 undocumented commands which mess with innduct's internal state and
172 should only be used by a developer in conjuction with the innduct
176 Start a new feed file and trigger a flush of the feed. (Or, cause
178 .I FLUSH-FINISH-PERIOD
179 to expire early, forcibly completing a previously started flush.)
182 Log statistics and exit. (Same effect as SIGTERM or SIGINT.)
185 Writes information about innduct's state to a plain text file
186 .IR feedfile \fB_dump\fR.
187 This overwrites any previous dump. innduct does not ever delete these
190 gives a summary including general state and a list of connections;
192 also includes information about each article innduct is dealing with.
195 Requests that innduct rescan for new backlog files at the next
197 poll. Normally innduct assumes that any backlog files dropped in by
198 the administrator are not urgent, and it may not get around to
200 .IR BACKLOG-SCAN-PERIOD .
203 Resets the connection startup delay counter so that innduct may
204 consider making a new connection to the peer right away, regardless
206 .IR RECONNECT-PERIOD .
207 A connection attempt will still only be made if innduct feels that it
208 needs one, and innduct may wait up to
210 before actually starting the attempt.
212 You should not normally need to adjust these. Time intervals may
213 specified in seconds, or as a number followed by one of the following
216 .BR "sec min hour day" ,
219 .BI \-\-max-connections= max
220 Restricts the maximum number of simultaneous NNTP connections
223 There is no global limit on the number of connections used by all
224 innducts, as the instances for different sites are entirely
229 .BI \-\-max-queue-per-conn= per-conn-max
230 Restricts the maximum number of outstanding articles queued on any
231 particular connection to
233 (Non-streaming connections can only handle one article at a time.)
237 .BI \-\-max-queue-per-file= max
238 Restricts the maximum number articles read into core from any one
245 .BI \-\-feedfile-flush-size= bytes
246 Specifies that innduct should flush the feed and start a new feedfile
247 when the existing feedfile size exceeds
249 the effect is that the innduct will try to avoid the various
250 batchfiles growing much beyond this size. The default is
253 .BI \-\-period-interval= PERIOD-INTERVAL
254 Specifies wakup interval and period granularity.
255 innduct wakes up every
257 to do various housekeeping checks. Also, many of the timeout and
258 rescan intervals (those specified in this manual as
260 are rounded up to the next multiple of
261 .IR PERIOD-INTERVAL .
265 .BI \-\-connection-timeout= TIME
266 How long to allow for a connection setup attempt before giving up.
270 .BI \-\-stuck-flush-timeout= TIME
271 How long to wait for innd to respond to a flush request before giving
275 .BI \-\-feedfile-poll= TIME
276 How often to poll the feedfile for new articles written by innd
279 or equivalent) is not available. (When file monitoring is available,
280 there is no need for periodic checks and we wake immediately up
281 whenever the feedfile changes.)
285 .BI \-\-no-check-proportion= PERCENT
286 If the moving average of the proportion of articles being accepted
287 (rather than declined) by the peer exceeds this value, innduct uses
288 "no check mode" - ie it just sends the peer the articles with TAKETHIS
289 rather than checking first with CHECK whether the article is wanted.
290 This only affects streaming connections. The default is
294 .BI \-\-no-check-response-time= ARTICLES
295 The moving average mentioned above is an alpha-smoothed value with a
301 .BI \-\-reconnect-interval= RECONNECT-PERIOD
302 Limits initiation of new connections to one each
303 .IR RECONNECT-PERIOD .
304 This applies to reconnections if the peer has been down, and also to
305 ramping up the number of connections we are using after startup or in
306 response to an article flood. The default is
309 .BI \-\-flush-retry-interval= PERIOD
310 If our attempt to flush the feed failed (usually this will be because
311 innd is not running), try again after
316 .BI \-\-earliest-deferred-retry= PERIOD
317 When the peer responds to our offer of an article with a 431 or 436
318 NNTP response code, indicating that the article has already been
319 offered to it by another of its peers, and that we should try again,
322 before offering the article again. The default is
325 .BI \-\-backlog-rescan-interval= BACKLOG-SCAN-PERIOD
326 We scan the directory containing
328 for backlog files at least every
329 .IR BACKLOG-SCAN-PERIOD ,
330 in case the administrator has manually dropped in a file there for
335 .BI \-\-max-flush-interval= PERIOD
336 We flush the feed and start a new feedfile at least every
338 even if the current instance of the feedfile has not reached the size
343 .BI \-\-flush-finish-timeout= FLUSH-FINISH-PERIOD
345 .IR FLUSH-FINISH-PERIOD
346 ago, and are still trying to finish processing articles that were
347 written to the old feed file, we forcibly and violently make sure that
348 we can finish the old feed file: we abandon and defer all the work,
349 which includes unceremoniously dropping any connections on which
350 we've sent some of those articles but not yet had replies, as they're
351 probably stuck somehow. The default is
354 .BI \-\-idle-timeout= PERIOD
355 Connections which have had no activity for
357 will be closed. This includes connections where we have sent commands
358 or articles but have not yet had the responses, so this same value
359 doubles as the timeout after which we conclude that the peer is
360 unresponsive or the connection has become broken.
364 .BI \-\-low-volume-thresh= "WIN-THRESH " \-\-low-volume-window= "PERIOD "
365 If innduct has only one connection to the peer, and has processed
370 and also no articles in the last
372 it will close the connection quickly. That is, innduct switches to a
373 mode where it opens a connection for each article (or, perhaps, each
374 handful of articles arriving together).
375 The default is to close if fewer than
380 .BI \-\-max-bad-input-data-ratio= PERCENT
381 We tolerate up to this proportion of badly-formatted lines in the
382 feedfile and other input files. Every badly-formatted line is logged,
383 but if there are too many we conclude that the corruption to our
384 on-disk data is too severe, and crash; to successfully restart,
385 administrator intervention will be required. This avoids flooding the
386 logs with warnings and also arranges to abort earlyish if an attempt
387 is made to process a file in the wrong format. We need to tolerate a
388 small proportion of broken lines, if for no other reason than that a
389 crash might leave a half-blanked-out entry. The default is
393 .BI \-\-max-bad-input-data-init= LINES
394 Additionally, we tolerate this number of additional badly-formatted
395 lines, so that if the badly-formatted lines are a few but at the start
396 of the file, we don't crash immediately.
399 (which would suffice to ignore one whole corrupt 4096-byte disk block
400 filled with random data, or one corrupt 1024-byte disk block filled
401 with an inappropriate text file with a mean line length of at least
403 .SH INNDUCT VS INNFEED/NNTPSEND/INNXMIT
406 does roughly the same thing as innduct. However, the way it receives
407 information from innd can result in articles being lost (not offered
408 to peers) if innfeed crashes for any reason. This is an inherent
409 defect in the innd channel feed protocol. innduct uses a file feed,
410 constantly "tailing" the feed file, and where implemented uses
412 to reduce the latency which would come from having to constantly poll
413 the feed file. innduct is much smaller and simpler, at <5kloc to
414 innfeed's ~25kloc. innfeed needs a separate helper script or similar
415 infrastructure (of which there is an example in its manpage), whereas
416 innduct can be run directly and doesn't need help from shell scripts.
417 However, innfeed is capable of feeding multiple peers from a single
418 innfeed instance, whereas each innduct process handles exactly one
422 processes feed files in batch mode. That is, you have to periodically
423 invoke nntpsend, and when you do, the feed is flushed and articles
424 which arrived before the flush are sent to the peer. This introduces
425 a batching delay, and also means that the NNTP connection to the peer
426 needs to be remade at each batch. nntpsend (which uses innxmit)
427 cannot make use of multiple connections to a single peer site.
428 However, nntpsend automatically find which sites need feeding by
431 whereas the administrator needs to arrange to invoke innduct
432 separately for each peer.
435 is the actual NNTP feeder program used by nntpsend.
440 \fBinnfeed\fR \fBinnduct\fR \fBnntpsend/innxmit\fR
441 realtime feed Yes Yes No
443 source code size 24kloc 4.6kloc 1.9kloc
444 invoke once for all sites Yes No Yes
445 number of processes one 1/site 2/site, intermittently
450 An instance of innduct is already running for this
457 The feed has been dropped by innd, and we (or previous innducts) have
458 successfully offered all the old articles to the peer site. Our work
462 innduct was invoked with bad options or command line arguments. The
463 error message will be printed to stderr, and also (if any options or
464 arguments were passed at all) to syslog with severity
468 Things are going wrong, hopefully shortage of memory, system file
469 table entries; disk IO problems; disk full; etc. The specifics of the
470 error will be logged to syslog with severity
472 (if syslog is working!)
475 Things are going badly wrong in an unexpected way: system calls which
476 are not expected to fail are doing so, or the protocol for
477 communicating with innd is being violated, or some such. Details will
478 be logged with severity
480 (if syslog is working!)
483 These exit statuses are used by children forked by innduct to
484 communicate to the parent. You should not see them. If you do, it is
487 innduct dances a somewhat complicated dance with innd to make sure
488 that everything goes smoothly and that there are no races. (See the
489 two ascii-art diagrams in innduct.c for details of the protocol.) Do
490 not mess with the feedfile and other associated files, other than as
494 .IX Item "default directory"
495 Default current working directory for innduct, and also default
496 grandparent directory for the command line socket.
497 .IP \fIpathoutgoing\fR/\fIsite\fR
498 .IX Item "default feedfile"
503 Main feed file as specified in
505 This and other batchfiles used by innduct contains lines each of which
507 \& \fItoken\fR \fImessageid\fR
508 where \fItoken\fR is the inn storage API token. Such lines can be
509 written by \fBTf,Wnm\fR in a \fInewsfeeds\fR(5) entry. During
510 processing, innduct overwrites lines in the batch files which
511 correspond to articles it has processed: each such line is replaced
512 with one containing only spaces. Only innd should create
514 and only innduct should remove it.
515 .IP \fIfeedfile\fR_lock
517 Lockfile, preventing multiple innduct invocations for the same
518 feed. A process holds this lock after it has opened the lockfile,
519 made an fcntl F_SETLK call, and then checked with stat and fstat that
520 the file it now has open and has locked still has the name
521 \fIfeedfile\fR_lock. (Only) the lockholder may delete the lockfile.
522 For your convenience, after the lockfile is locked,
529 are all written to the lockfile. NB that stale lockfiles may contain
530 stale data so this information should not be relied on other than for
532 .IP \fIfeedfile\fR_flushing
533 .IX Item "flushing file"
534 Batch file: the main feedfile is renamed to this filename by innduct
535 before it asks inn to flush the feed. Only innduct should create,
536 modify or remove this file.
537 .IP \fIfeedfile\fR_defer
538 .IX Item "flushing file"
539 Batch file containing details of articles whose transmission has very
540 recently been deferred at the request of the recipient site. Created,
541 written, read and removed (only) by innduct.
542 .IP \fIfeedfile\fR_backlog.\fItime_t\fR.\fIinum\fR
543 .IX Item "backlog file"
544 Batch file containing details of articles whose transmission has less
545 recently been deferred at the request of the recipient site. Created
546 by innduct, and will also be read, updated and removed by innduct.
547 However you (the administrator) may also safely remove backlog files.
548 .IP \fIfeedfile\fR_backlog\fIsomething\fR
549 .IX Item "manual backlog file"
550 Batch file manually provided by the administrator. innduct will
551 automatically find, read and process any file matching this pattern
552 (blanking out entries for processed articles) and eventually remove
553 it. \fIsomething\fR may not contain \fB#\fR \fB~\fR or \fB/\fR.
555 Be sure to have finished writing the file before you rename it to
556 match the pattern \fIfeedfile\fR\fB_backlog\fR*, as otherwise innduct
557 may find and process the file, and even think it has finished it,
558 before you have written the complete file. You may also safely remove
560 .IP \fIpathrun\fR\fB/innduct/\fB\fIsite\fR
561 .IX Item "control command line socket"
562 Default AF_UNIX listening socket for the control command line. See
563 CONTROLLING INNDUCT, above.
564 .IP \fIfeedfile\fR_dump
565 .IX Item "debug dump file"
566 On request via a control connection innduct dumps a summary of its
567 state to this text file. This is mostly useful for debugging.
568 .IP /etc/news/inn.conf
574 and associated paths),
578 and hence effective default
582 for finding how to communicate with innd, and also for
587 Written by Ian Jackson <ijackson@chiark.greenend.org.uk>
~ian / innduct.git / blob