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