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