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