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