chiark / gitweb /
Debianisation (initial cut)
[innduct.git] / innduct.8
1 '\" t
2 .TH INNDUCT 8
3 .SH NAME
4 innduct \- quickly and reliably stream Usenet articles to remote site
5 .SH SYNOPSIS
6 .B innduct
7 .RI [ options ]
8 .I site
9 .RI [ fqdn ]
10 .SH DESCRIPTION
11 .B innduct
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
15 .B innfeed
16 or
17 .BR nntpsend
18 and
19 .BR innxmit .
20
21 You need to run one instance of innduct for each peer site.  innduct
22 manages its interaction with
23 .BR innd ,
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.
28
29 By default, innduct reads the default feedfile corresponding to
30 the site
31 .I site
32 (ie
33 .IR pathoutgoing / site )
34 and feeds it via NNTP, streaming if possible, to the host
35 .IR fqdn .
36 If
37 .I fqdn
38 is not specified, it defaults to
39 .IR site .
40
41 innduct daemonises after argument parsing, and all logging (including
42 error messages) are sent to syslog (facility
43 .BR news ).
44
45 The best way to run innduct is probably to periodically invoke it
46 for each feed (e.g. from cron), passing the
47 .B \-q
48 option to arrange that innduct silently exits if an instance is
49 already running for that site.
50 .SH GENERAL OPTIONS
51 .TP
52 .BR \-f | \-\-feedfile= \fIDIR\fR / |\fIPATH\fR
53 Specifies the
54 .I feedfile
55 to read, and indirectly specifies the paths to
56 be used for various associated files (see FILES, below).
57 If specified as
58 .IB DIR /
59 it is taken as a directory to use, and the actual feed file used is
60 .IR path / site .
61 If
62 .I PATH
63 or
64 .I DIR
65 does not start with a
66 .BR / ,
67 it is taken to be relative to
68 .IR pathoutgoing
69 from inn.conf.
70 The default is
71 .IR site .
72 .TP
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.
77 .TP
78 .BR \-\-no-daemon
79 Do not daemonise.  innduct runs in the foreground, but otherwise
80 operates normally (logging to syslog, etc.).
81 .TP
82 .BR \-\-interactive
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.
86 .TP
87 .BI \-\-no-streaming
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).
90 .TP
91 .BI \-\-no-filemon
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.)
96 .TP
97 .BR \-C | \-\-inndconf= \fIFILE\fR
98 Read
99 .I FILE
100 instead of the default
101 .BR inn.conf .
102 .TP
103 .BI \-\-port= PORT
104 Connect to port
105 .I PORT
106 at the remote site rather than to the NNTP port (119).
107 .TP
108 .BI \-\-chdir= PATHRUN
109 Change directory to
110 .IR pathrun
111 at startup.  The default is
112 .I pathrun
113 from inn.conf.
114 .TP
115 .BR \-\-cli= \fICLI-DIR\fR / |\fICLI-PATH\fR| none
116 Listen for control command line connections on
117 .IB CLI-DIR / site
118 (if the value ends with a
119 .BR /)
120 or
121 .I CLI-PATH
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
125 .IR CLI-DIR \fB/\fR,
126 the directory will be created with mode 700 if necessary.
127 The default is
128 .B innduct/
129 which means to create that directory in
130 .I PATHRUN
131 and listen on
132 .RB \fIPATHRUN\fR /innduct/ \fIsite\fR.
133 .TP
134 .BI \-\-help
135 Just print a brief usage message and list of the options to stdout.
136 .LP
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).
144 .LP
145 If you want to stop innduct you can send it SIGTERM or SIGINT, or the
146 .B stop
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.
150 .LP
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
158 .I netcat-openbsd
159 (eg
160 .B nc.openbsd -U
161 .RI \fB/var/run/news/innduct/\fR site )
162 or
163 .IR socat .
164 The prompt is
165 .IR site \fB|\fR.
166 .LP
167 The following control commands are supported:
168 .TP
169 .B h
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
173 source code.
174 .TP
175 .B flush
176 Start a new feed file and trigger a flush of the feed.  (Or, cause
177 the
178 .I FLUSH-FINISH-PERIOD
179 to expire early, forcibly completing a previously started flush.)
180 .TP
181 .B stop
182 Log statistics and exit.  (Same effect as SIGTERM or SIGINT.)
183 .TP
184 .B logstats
185 Log statistics so far and zero the stats counters.  Stats are also
186 logged periodically, when an input file is completed and just before
187 tidy termination.
188 .TP
189 .BR show
190 Writes summary information about innduct's state to the current CLI
191 connection.
192 .TP
193 .BR "dump q" | a
194 Writes the same information about innduct's state to a plain text file
195 .IR feedfile \fB_dump\fR.
196 This overwrites any previous dump.  innduct does not ever delete these
197 dump files.
198 .B "dump q"
199 gives a summary including general state and a list of connections;
200 .B "dump a"
201 also includes information about each article innduct is dealing with.
202 .TP
203 .B next blscan
204 Requests that innduct rescan for new backlog files at the next
205 .I PERIOD
206 poll.  Normally innduct assumes that any backlog files dropped in by
207 the administrator are not urgent, and it may not get around to
208 noticing them for
209 .IR BACKLOG-SCAN-PERIOD .
210 .TP
211 .B next conn
212 Resets the connection startup delay counter so that innduct may
213 consider making a new connection to the peer right away, regardless
214 of the setting of
215 .IR RECONNECT-PERIOD .
216 A connection attempt will still only be made if innduct feels that it
217 needs one, and innduct may wait up to
218 .I PERIOD
219 before actually starting the attempt.
220 .SH TUNING OPTIONS
221 You should not normally need to adjust these.  Time intervals may
222 specified in seconds, or as a number followed by one of the following
223 units:
224 .BR "s m h d" ,
225 .BR "sec min hour day" ,
226 .BR "das hs ks Ms" .
227 .TP
228 .BI \-\-max-connections= max
229 Restricts the maximum number of simultaneous NNTP connections
230 per peer to
231 .IR max .
232 There is no global limit on the number of connections used by all
233 innducts, as the instances for different sites are entirely
234 independent.
235 The default is
236 .BR 10 .
237 .TP
238 .BI \-\-max-queue-per-conn= per-conn-max
239 Restricts the maximum number of outstanding articles queued on any
240 particular connection to
241 .IR max .
242 (Non-streaming connections can only handle one article at a time.)
243 The default is
244 .BR 200 .
245 .TP
246 .BI \-\-max-queue-per-file= max
247 Restricts the maximum number articles read into core from any one
248 input file to
249 .IR max .
250 The default is
251 .B twice
252 .IR per-conn-max .
253 .TP
254 .BI \-\-feedfile-flush-size= bytes
255 Specifies that innduct should flush the feed and start a new feedfile
256 when the existing feedfile size exceeds
257 .IR bytes ;
258 the effect is that the innduct will try to avoid the various
259 batchfiles growing much beyond this size.  The default is
260 .BR 100000 .
261 .TP
262 .BI \-\-period-interval= PERIOD-INTERVAL
263 Specifies wakup interval and period granularity.
264 innduct wakes up every
265 .I PERIOD-INTERVAL
266 to do various housekeeping checks.  Also, many of the timeout and
267 rescan intervals (those specified in this manual as
268 .IR PERIOD )
269 are rounded up to the next multiple of
270 .IR PERIOD-INTERVAL .
271 The default is
272 .BR 30s .
273 .TP
274 .BI \-\-connection-timeout= TIME
275 How long to allow for a connection setup attempt before giving up.
276 The default is
277 .BR 200s .
278 .TP
279 .BI \-\-stuck-flush-timeout= TIME
280 How long to wait for innd to respond to a flush request before giving
281 up.  The default is
282 .BR 100s .
283 .TP
284 .BI \-\-feedfile-poll= TIME
285 How often to poll the feedfile for new articles written by innd
286 if file monitoring
287 .RI ( inotify
288 or equivalent) is not available.  (When file monitoring is available,
289 there is no need for periodic checks and we wake immediately up
290 whenever the feedfile changes.)
291 The default is
292 .BR 5s .
293 .TP
294 .BI \-\-no-check-proportion= PERCENT
295 If the moving average of the proportion of articles being accepted
296 (rather than declined) by the peer exceeds this value, innduct uses
297 "no check mode" - ie it just sends the peer the articles with TAKETHIS
298 rather than checking first with CHECK whether the article is wanted.
299 This only affects streaming connections.  The default is
300 .B 95
301 (ie, 95%).
302 .TP
303 .BI \-\-no-check-response-time= ARTICLES
304 The moving average mentioned above is an alpha-smoothed value with a
305 half-life of
306 .IR ARTICLES .
307 The default is
308 .BR 100 .
309 .TP
310 .BI \-\-reconnect-interval= RECONNECT-PERIOD
311 Limits initiation of new connections to one each
312 .IR RECONNECT-PERIOD .
313 This applies to reconnections if the peer has been down, and also to
314 ramping up the number of connections we are using after startup or in
315 response to an article flood.  The default is
316 .BR 1000s .
317 .TP
318 .BI \-\-flush-retry-interval= PERIOD
319 If our attempt to flush the feed failed (usually this will be because
320 innd is not running), try again after
321 .IR PERIOD .
322 The default is
323 .BR 1000s .
324 .TP
325 .BI \-\-earliest-deferred-retry= PERIOD
326 When the peer responds to our offer of an article with a 431 or 436
327 NNTP response code, indicating that the article has already been
328 offered to it by another of its peers, and that we should try again,
329 we wait at least
330 .IR PERIOD .
331 before offering the article again.  The default is
332 .BR 100s .
333 .TP
334 .BI \-\-backlog-rescan-interval= BACKLOG-SCAN-PERIOD
335 We scan the directory containing
336 .I feedfile
337 for backlog files at least every
338 .IR BACKLOG-SCAN-PERIOD ,
339 in case the administrator has manually dropped in a file there for
340 processing.
341 The default is
342 .BR 300s .
343 .TP
344 .BI \-\-max-flush-interval= PERIOD
345 We flush the feed and start a new feedfile at least every
346 .IR PERIOD
347 even if the current instance of the feedfile has not reached the size
348 threshold.
349 The default is
350 .BR 100000s .
351 .TP
352 .BI \-\-flush-finish-timeout= FLUSH-FINISH-PERIOD
353 If we flushed
354 .IR FLUSH-FINISH-PERIOD
355 ago, and are still trying to finish processing articles that were
356 written to the old feed file, we forcibly and violently make sure that
357 we can finish the old feed file: we abandon and defer all the work,
358 which includes unceremoniously dropping any connections on which
359 we've sent some of those articles but not yet had replies, as they're
360 probably stuck somehow.  The default is
361 .BR 2000s .
362 .TP
363 .BI \-\-idle-timeout= PERIOD
364 Connections which have had no activity for
365 .IR PERIOD
366 will be closed.  This includes connections where we have sent commands
367 or articles but have not yet had the responses, so this same value
368 doubles as the timeout after which we conclude that the peer is
369 unresponsive or the connection has become broken.
370 The default is
371 .BR 1000s .
372 .TP
373 .BI \-\-stats-log-interval= PERIOD
374 Log statistics at least every
375 .IR PERIOD
376 The default is
377 .BR 2500s .
378 .TP
379 .BI \-\-low-volume-thresh= "WIN-THRESH " \-\-low-volume-window= "PERIOD "
380 If innduct has only one connection to the peer, and has processed
381 fewer than
382 .I WIN-THRESH
383 articles in the last
384 .I PERIOD
385 and also no articles in the last
386 .IR PERIOD-INTERVAL
387 it will close the connection quickly.  That is, innduct switches to a
388 mode where it opens a connection for each article (or, perhaps, each
389 handful of articles arriving together).
390 The default is to close if fewer than
391 .BR 3
392 articles in the last
393 .BR 1000s .
394 .TP
395 .BI \-\-max-bad-input-data-ratio= PERCENT
396 We tolerate up to this proportion of badly-formatted lines in the
397 feedfile and other input files.  Every badly-formatted line is logged,
398 but if there are too many we conclude that the corruption to our
399 on-disk data is too severe, and crash; to successfully restart,
400 administrator intervention will be required.  This avoids flooding the
401 logs with warnings and also arranges to abort earlyish if an attempt
402 is made to process a file in the wrong format.  We need to tolerate a
403 small proportion of broken lines, if for no other reason than that a
404 crash might leave a half-blanked-out entry.  The default is
405 .BR 1
406 (ie, 1%).
407 .TP
408 .BI \-\-max-bad-input-data-init= LINES
409 Additionally, we tolerate this number of additional badly-formatted
410 lines, so that if the badly-formatted lines are a few but at the start
411 of the file, we don't crash immediately.
412 The default is
413 .BR 30
414 (which would suffice to ignore one whole corrupt 4096-byte disk block
415 filled with random data, or one corrupt 1024-byte disk block filled
416 with an inappropriate text file with a mean line length of at least
417 35).
418 .SH INNDUCT VS INNFEED/NNTPSEND/INNXMIT
419 .TP
420 .B innfeed
421 does roughly the same thing as innduct.  However, the way it receives
422 information from innd can result in articles being lost (not offered
423 to peers) if innfeed crashes for any reason.  This is an inherent
424 defect in the innd channel feed protocol.  innduct uses a file feed,
425 constantly "tailing" the feed file, and where implemented uses
426 .BR inotify (2)
427 to reduce the latency which would come from having to constantly poll
428 the feed file.  innduct is much smaller and simpler, at <5kloc to
429 innfeed's ~25kloc.  innfeed needs a separate helper script or similar
430 infrastructure (of which there is an example in its manpage), whereas
431 innduct can be run directly and doesn't need help from shell scripts.
432 However, innfeed is capable of feeding multiple peers from a single
433 innfeed instance, whereas each innduct process handles exactly one
434 peer.
435 .TP
436 .B nntpsend
437 processes feed files in batch mode.  That is, you have to periodically
438 invoke nntpsend, and when you do, the feed is flushed and articles
439 which arrived before the flush are sent to the peer.  This introduces
440 a batching delay, and also means that the NNTP connection to the peer
441 needs to be remade at each batch.  nntpsend (which uses innxmit)
442 cannot make use of multiple connections to a single peer site.
443 However, nntpsend automatically find which sites need feeding by
444 looking in
445 .IR pathoutgoing ,
446 whereas the administrator needs to arrange to invoke innduct
447 separately for each peer.
448 .TP
449 .B innxmit
450 is the actual NNTP feeder program used by nntpsend.
451 .LP
452 .TS
453 l l l l.
454         \fBinnfeed\fR   \fBinnduct\fR   \fBnntpsend/innxmit\fR
455 realtime feed   Yes     Yes     No
456 reliable        No      Yes     Yes
457 source code size        24kloc  4.6kloc 1.9kloc
458 invoke once for all sites       Yes     No      Yes
459 number of processes     one     1/site  2/site, intermittently
460 .TE
461 .SH EXIT STATUS
462 .TP
463 .B 0
464 An instance of innduct is already running for this
465 .I feedfile
466 and
467 .B -q
468 was specified.
469 .TP
470 .B 4
471 The feed has been dropped by innd, and we (or previous innducts) have
472 successfully offered all the old articles to the peer site.  Our work
473 is done.
474 .TP
475 .B 8
476 innduct was invoked with bad options or command line arguments.  The
477 error message will be printed to stderr, and also (if any options or
478 arguments were passed at all) to syslog with severity
479 .BR crit .
480 .TP
481 .B 12
482 Things are going wrong, hopefully shortage of memory, system file
483 table entries; disk IO problems; disk full; etc.  The specifics of the
484 error will be logged to syslog with severity
485 .B err
486 (if syslog is working!)
487 .TP
488 .B 16
489 Things are going badly wrong in an unexpected way: system calls which
490 are not expected to fail are doing so, or the protocol for
491 communicating with innd is being violated, or some such.  Details will
492 be logged with severity
493 .B crit
494 (if syslog is working!)
495 .TP
496 .BR 24 - 27
497 These exit statuses are used by children forked by innduct to
498 communicate to the parent.  You should not see them.  If you do, it is
499 a bug.
500 .SH FILES
501 innduct dances a somewhat complicated dance with innd to make sure
502 that everything goes smoothly and that there are no races.  (See the
503 two ascii-art diagrams in README.states for details of the protocol.)  Do
504 not mess with the feedfile and other associated files, other than as
505 explained here:
506 .IX Header "FILES"
507 .IP \fIpathrun\fR
508 .IX Item "default directory"
509 Default current working directory for innduct, and also default
510 grandparent directory for the command line socket.
511 .IP \fIpathoutgoing\fR/\fIsite\fR
512 .IX Item "default feedfile"
513 Default
514 .IR feedfile .
515 .IP \fIfeedfile\fR
516 .IX Item feedfile
517 Main feed file as specified in
518 .IR newsfeeds (5).
519 This and other batchfiles used by innduct contains lines each of which
520 is of the form
521 \&    \fItoken\fR \fImessageid\fR
522 where \fItoken\fR is the inn storage API token.  Such lines can be
523 written by \fBTf,Wnm\fR in a \fInewsfeeds\fR(5) entry.  During
524 processing, innduct overwrites lines in the batch files which
525 correspond to articles it has processed: each such line is replaced
526 with one containing only spaces.  Only innd should create
527 .IR feedfile ,
528 and only innduct should remove it.
529 .IP \fIfeedfile\fR_lock
530 .IX Item "lock file"
531 Lockfile, preventing multiple innduct invocations for the same
532 feed.  A process holds this lock after it has opened the lockfile,
533 made an fcntl F_SETLK call, and then checked with stat and fstat that
534 the file it now has open and has locked still has the name
535 \fIfeedfile\fR_lock.  (Only) the lockholder may delete the lockfile.
536 For your convenience, after the lockfile is locked,
537 .IR innfeed 's
538 pid, the
539 .IR site ,
540 .IR feedfile
541 and
542 .IR fqdn
543 are all written to the lockfile.  NB that stale lockfiles may contain
544 stale data so this information should not be relied on other than for
545 troubleshooting.
546 .IP \fIfeedfile\fR_flushing
547 .IX Item "flushing file"
548 Batch file: the main feedfile is renamed to this filename by innduct
549 before it asks inn to flush the feed.  Only innduct should create,
550 modify or remove this file.
551 .IP \fIfeedfile\fR_defer
552 .IX Item "flushing file"
553 Batch file containing details of articles whose transmission has very
554 recently been deferred at the request of the recipient site.  Created,
555 written, read and removed (only) by innduct.
556 .IP \fIfeedfile\fR_backlog.\fItime_t\fR.\fIinum\fR
557 .IX Item "backlog file"
558 Batch file containing details of articles whose transmission has less
559 recently been deferred at the request of the recipient site.  Created
560 by innduct, and will also be read, updated and removed by innduct.
561 However you (the administrator) may also safely remove backlog files.
562 .IP \fIfeedfile\fR_backlog\fIsomething\fR
563 .IX Item "manual backlog file"
564 Batch file manually provided by the administrator.  innduct will
565 automatically find, read and process any file matching this pattern
566 (blanking out entries for processed articles) and eventually remove
567 it.  \fIsomething\fR may not contain \fB#\fR \fB~\fR or \fB/\fR.
568 .IP
569 Be sure to have finished writing the file before you rename it to
570 match the pattern \fIfeedfile\fR\fB_backlog\fR*, as otherwise innduct
571 may find and process the file, and even think it has finished it,
572 before you have written the complete file.  You may also safely remove
573 backlog files.
574 .IP \fIpathrun\fR\fB/innduct/\fB\fIsite\fR
575 .IX Item "control command line socket"
576 Default AF_UNIX listening socket for the control command line.  See
577 CONTROLLING INNDUCT, above.
578 .IP \fIfeedfile\fR_dump
579 .IX Item "debug dump file"
580 On request via a control connection innduct dumps a summary of its
581 state to this text file.  This is mostly useful for debugging.
582 .IP /etc/news/inn.conf
583 .IX Item inn.conf
584 Used for
585 .IR pathoutgoing
586 (to compute default
587 .IR feedfile
588 and associated paths),
589 .IR pathrun
590 (to compute default
591 .IR PATHRUN
592 and hence effective default
593 .IR CLI-DIR
594 and
595 .IR CLI-PATH ),
596 for finding how to communicate with innd, and also for
597 .IR sourceaddress
598 and/or
599 .IR sourceaddress6 .
600 .SH HISTORY
601 Written by Ian Jackson <ijackson@chiark.greenend.org.uk>
602 .SH "SEE ALSO"
603 inn.conf(5),
604 innd(8),
605 newsfeeds(5)