chiark / gitweb /
Option for setting realsockdir
[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 3kloc 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.
92 .TP
93 .BI \-\-no-streaming
94 Do not try to use the streaming extensions to NNTP (for use eg if the
95 peer can't cope when we send MODE STREAM).
96 .TP
97 .BI \-\-no-filemon
98 Do not try to use the file change monitoring support to watch for
99 writes by innd to the feed file; poll it instead.  (If file monitoring
100 is not compiled in, this option just downgrades the log message which
101 warns about this situation.)
102 .TP
103 .BR \-C | \-\-inndconf= \fIFILE\fR
104 Read
105 .I FILE
106 instead of the default
107 .BR inn.conf .
108 .TP
109 .BI \-\-ctrl-sock-dir= DIR
110 Bind the real control socket to a unique filename in
111 .IR DIR .
112 A symlink will be made pointing to the actual file used, named
113 .IB feedfile _control
114 in the same directory as
115 .IR feedfile ,
116 but since
117 .IR feedfile 's
118 path may be too long for an AF_UNIX socket path, innduct always
119 creates the sockets in this dedicated directory which is expected to
120 have a short path.  If
121 .I DIR
122 does not exist it will be created with mode 0700; if it does
123 exist it must not be a symlink and must be owned by the user running
124 innduct and have no access for "other".  If the control socket cannot
125 be set up (for this or any other reason), a warning is logged, but
126 such situations are not fatal for innduct's startup.  The default is
127 .BR /tmp/innduct.control .
128 .TP
129 .BI \-\-port= PORT
130 Connect to port
131 .I PORT
132 at the remote site rather than to the NNTP port (119).
133 .TP
134 .BI \-\-help
135 Just print a brief usage message and list of the options to stdout.
137 You should not normally need to adjust these.  Time intervals may
138 specified in seconds, or as a number followed by one of the following
139 units:
140 .BR "s m h d" ,
141 .BR "sec min hour day" ,
142 .BR "das hs ks Ms" .
143 .TP
144 .BI \-\-max-connections= max
145 Restricts the maximum number of simultaneous NNTP connections used by
146 for each site to
147 .IR max .
148 The default is
149 .BR 10 .
150 There is no global limit on the number of connections.
151 .TP
152 .BI \-\-max-queue-per-conn= max
153 Restricts the maximum number of outstanding articles queued on any
154 particular connection
155 .IR max .
156 (Non-streaming connections can only handle one article at a time.)
157 The default is
158 .BR 200 .
159 .TP
160 .BI \-\-feedfile-flush-size= bytes
161 Specifies that innduct should flush the feed and start a new feedfile
162 when the existing feedfile size exceeds
163 .IR bytes ;
164 the effect is that the innduct will try to avoid the various
165 batchfiles growing much beyond this size while the link to the peer is
166 working.  The default is
167 .BR 100000 .
168 .TP
169 .BI \-\-period-interval= PERIOD-INTERVAL
170 Specifies wakup interval and period granularity.
171 innduct wakes up every
173 to do various housekeeping checks.  Also, many of the timeout and
174 rescan intervals (those specified in this manual as
175 .IR PERIOD )
176 are rounded up to the next multiple of
178 .TP
179 .BI \-\-connection-timeout= TIME
180 How long to allow for a connection setup attempt before giving up.
181 The default is
182 .BR 200s .
183 .TP
184 .BI \-\-stuck-flush-timeout= TIME
185 How long to wait for innd to respond to a flush request before giving
186 up.  The default is
187 .BR 100s .
188 .TP
189 .BI \-\-feedfile-poll= TIME
190 How often to poll the feedfile for new articles written by innd
191 if file monitoring
192 .RI ( inotify
193 or equivalent) is not available.  (When file monitoring is available,
194 there is no need for periodic checks and we wake immediately up
195 whenever the feedfile changes.)
196 The default is
197 .BR 5s .
198 .TP
199 .BI \-\-no-check-proportion= PERCENT
200 If the moving average of the proportion of articles being accepted
201 (rather than declined) by the peer exceeds this value, innduct uses
202 "no check mode" - ie it just sends the peer the articles with TAKETHIS
203 rather than checking first with CHECK whether the article is wanted.
204 This only affects streaming connections.  The default is
205 .B 95
206 (ie, 95%).
207 .TP
208 .BI \-\-no-check-response-time= ARTICLES
209 The moving average mentioned above is an alpha-smoothed value with a
210 half-life of
212 The default is
213 .BR 100 .
214 .TP
215 .BI \-\-reconnect-interval= PERIOD
216 Limits initiation of new connections to one each
217 .IR PERIOD .
218 This applies to reconnections if the peer has been down, and also to
219 ramping up the number of connections we are using after startup or in
220 response to an article flood.  The default is
221 .BR 1000s .
222 .TP
223 .BI \-\-flush-retry-interval= PERIOD
224 If our attempt to flush the feed failed (usually this will be because
225 innd is not running), try again after
226 .IR PERIOD .
227 The default is
228 .BR 1000s .
229 .TP
230 .BI \-\-earliest-deferred-retry= PERIOD
231 When the peer responds to our offer of an article with a 431 or 436
232 NNTP response code, indicating that the article has already been
233 offered to it by another of its peers, and that we should try again,
234 we wait at least
235 .IR PERIOD .
236 before offering the article again.  The default is
237 .BR 50s .
238 .TP
239 .BI \-\-backlog-rescan-interval= PERIOD
240 We scan the directory containing
241 .I feedfile
242 for backlog files at least every
243 .IR PERIOD ,
244 in case the administrator has manually dropped in a file there for
245 processing.
246 The default is
247 .TP
248 .BI \-\-max-flush-interval= PERIOD
249 We flush the feed at least every
251 even if the current instance of the feedfile has not reached the size
252 threshold.
253 The default is
254 .BR 100000s .
255 .TP
256 .BI \-\-max-flush-interval= PERIOD
257 We flush the feed and start a new feedfile at least every
259 even if the current instance of the feedfile has not reached the size
260 threshold.
261 The default is
262 .BR 100000s .
263 .TP
264 .BI \-\-idle-timeout= PERIOD
265 Connections which have had no activity for
267 will be closed.  This includes connections where we have sent commands
268 or articles but have not yet had the responses, so this same value
269 doubles as the timeout after which we conclude that the peer is
270 unresponsive or the connection has become broken.
271 The default is
272 .BR 1000s .
273 .TP
274 .BI \-\-max-bad-input-data-ratio= PERCENT
275 We tolerate up to this proportion of badly-formatted lines in the
276 feedfile and other input files.  Every badly-formatted line is logged,
277 but if there are too many we conclude that the corruption to our
278 on-disk data is too severe, and crash; to successfully restart,
279 administrator intervention will be required.  This avoids flooding the
280 logs with warnings and also arranges to abort earlyish if an attempt
281 is made to process a file in the wrong format.
282 The default is
283 .BR 1
284 (ie, 1%).
285 .TP
286 .BI \-\-max-bad-input-data-init= LINES
287 Additionally, we tolerate this number of additional badly-formatted
288 lines, so that if the badly-formatted lines are a few but at the start
289 of the file, we don't crash immediately.
290 The default is
291 .BR 30
292 (which would suffice to ignore one whole corrupt 4096-byte disk block
293 filled with random data, or one corrupt 1024-byte disk block filled
294 with an inappropriate text file with a mean line length of at least
295 35).
297 innduct dances a somewhat complicated dance with innd to make sure
298 that everything goes smoothly and that there are no races.  (See the
299 two ascii-art diagrams in innduct.c for details of the protocol.)  Do
300 not mess with the feedfile and other associated files, other than as
301 explained below in the section
302 .BR FILES .
303 .LP
304 If you tell innd to drop the feed, innduct will (when it notices,
305 which will normally be the next time it decides flushes) finish up the
306 articles it has in hand now, and then exit.  It is harmless to cause
307 innd to flush the feed (but innduct won't notice and flushing won't
308 start a new feedfile; you have to leave that to innduct).
309 .LP
310 There are no signals that can usefully be sent to innduct to give it
311 complicated instructions.  If you need to kill innduct, feel free to
312 send it a
314 or
316 and nothing will be broken or corrupted.
318 .TP
319 .B 0
320 An instance of innduct is already running for this
321 .I feedfile
322 and
323 .B -q
324 was specified.
325 .TP
326 .B 4
327 The feed has been dropped by innd, and we (or previous innducts) have
328 successfully offered all the old articles to the peer site.  Our work
329 is done.
330 .TP
331 .B 8
332 innduct was invoked with bad options or command line arguments.  The
333 error message will be printed to stderr, and also (if any options or
334 arguments were passed at all) to syslog with severity
335 .BR crit .
336 .TP
337 .B 12
338 Things are going wrong, hopefully shortage of memory, system file
339 table entries; disk IO problems; disk full; etc.  The specifics of the
340 error will be logged to syslog with severity
341 .B err
342 (if syslog is working!)
343 .TP
344 .B 16
345 Things are going badly wrong in an unexpected way: system calls which
346 are not expected to fail are doing so, or the protocol for
347 communicating with innd is being violated, or some such.  Details will
348 be logged with severity
349 .B crit
350 (if syslog is working!)
351 .TP
352 .BR 24 - 27
353 These exit statuses are used by children forked by innduct to
354 communicate to the parent.  You should not see them.  If you do, it is
355 a bug.
357 .IX Header "FILES"
358 .IP \fIpathoutgoing\fR/\fIsite\fR
359 .IX Item "default feedfile"
360 Default
361 .IR feedfile .
362 .IP \fIfeedfile\fR
363 .IX Item feedfile
364 Main feed file as specified in
365 .IR newsfeeds (5).
366 This and other batchfiles used by innduct contains lines each of which
367 is of the form
368 \&    \fItoken\fR \fImessageid\fR
369 where \fItoken\fR is the inn storage API token.  Such lines can be
370 written by \fBTf,Wnm\fR in a \fInewsfeeds\fR(5) entry.  During
371 processing, innduct overwrites lines in the batch files which
372 correspond to articles it has processed: the line is replaced with
373 one containing only spaces.  Only innd should create this file, and
374 only innduct should remove it.
375 .IP \fIfeedfile\fR_lock
376 .IX Item "lock file"
377 Lockfile, preventing multiple innduct invocations for the same
378 feed.  A process holds this lock after it has opened the lockfile,
379 made an fcntl F_SETLK call, and then checked with stat and fstat that
380 the file it now has open and has locked still has the name
381 \fIfeedfile\fR_lock.  (Only) the lockholder may delete the lockfile.
382 For your convenience, after the lockfile is locked,
383 .IR innfeed 's
384 pid, the
385 .IR site ,
386 .IR feedfile
387 and
388 .IR fqdn
389 are all written to the lockfile.  NB that stale lockfiles may contain
390 stale data so this information should not be relied on other than for
391 troubleshooting.
392 .IP \fIfeedfile\fR_flushing
393 .IX Item "flushing file"
394 Batch file: the main feedfile is renamed to this filename by innduct
395 before it asks inn to flush the feed.  Only innduct should create or
396 remove this file.
397 .IP \fIfeedfile\fR_defer
398 .IX Item "flushing file"
399 Batch file containing details of articles whose transmission has
400 recently been deferred at the request of the recipient site.  Created,
401 written, read and removed by innduct.
402 .IP \fIfeedfile\fR_backlog.\fItime_t\fR.\fIinum\fR
403 .IX Item "backlog file"
404 Batch file containing details of articles whose transmission has less
405 recently been deferred at the request of the recipient site.  Created
406 by innduct, and will also be read and removed by innduct.  However you
407 (the administrator) may also safely remove backlog files.
408 .IP \fIfeedfile\fR_backlog\fIsomething\fR
409 .IX Item "manual backlog file"
410 Batch file manually provided by the administrator.  The file should be
411 complete and ready to process at the time it is renamed or hardlinked
412 to this name.  innduct will then automatically find and read and
413 process it and eventually remove it.  The administrator may also
414 safely remove backlog files.  \fIsomething\fR may not contain \fB#\fR
415 \fB~\fR or \fB/\fR.  Be sure to have finished writing the file before
416 you rename it to match the pattern \fIfeedfile\fR\fB_backlog\fR*, as
417 otherwise innduct may find and process the file and read it to EOF
418 before you have finished creating it.
419 .IP /etc/news/inn.conf
420 .IX Item inn.conf
421 Used to find
422 .IR pathoutgoing
423 if none is specified, for finding how to communicate with innd,
424 and also for
425 .IR sourceaddress
426 and/or
427 .IR sourceaddress6 .
429 Written by Ian Jackson <>
430 .SH "SEE ALSO"
431 inn.conf(5),
432 newsfeeds(5)