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