chiark / gitweb /
Proposed exit statuses
[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 Logging is sent to syslog.
34 .SH GENERAL OPTIONS
35 .TP
36 .BI \-f feedfile
37 Specifies
38 .IR feedfile .
39 If the specified value ends in a
40 .B /
41 it is taken as a directory to use as if it were
42 .I pathoutgoing
43 and the actual feed file used is
44 .IR specified_feedfile / site .
45 .TP
46 .BR \-q | \-\-quiet-multiple
47 Makes innduct silently exit if another innduct holds the lock for the
48 site.  Without \fB-q\fR, this causes a fatal error to be logged.
49 .SH TUNING OPTIONS
50 You should not normally need to adjust these.
51 .TP
52 .BI \-\-max-connections= max
53 Restricts the maximum number of simultaneous NNTP connections used by
54 for each site to
55 .IR max .
56 The default is 10.  There is no global limit on the number of
57 connections.
58 .TP
59 .BI \-\-max-queue-per-conn= max
60 Restricts the maximum number of outstanding articles queued on any
61 particular connection
62 .IR max .
63 The default is 200.  (Non-streaming connections can only handle one
64 article at a time.)
65 .TP
66 .BI \-\-max-queue-per-conn= max
67 Restricts the maximum number of outstanding articles queued on any
68 particular connection
69 .IR max .
70 The default is 200.
71 .SH EXIT STATUS
72 0 ok
73 4 one is already running
74 8 bad usage
75 12 trouble
76 .SH FILES
77 .IX Header "FILES"
78 .IP \fIpathoutgoing\fR/\fIsite\fR
79 .IX Item "default feedfile"
80 Default
81 .IR feedfile .
82 .IP \fIfeedfile\fR
83 .IX Item feedfile
84 Main feed file as specified in
85 .IR newsfeeds (5).
86 This and other batchfiles used by innduct contains lines each of which
87 is of the form
88 \&    \fItoken\fR \fImessageid\fR
89 where \fItoken\fR is the inn storage API token.  Such lines can be
90 written by \fBTf,Wnm\fR in a \fInewsfeeds\fR(5) entry.  During
91 processing, innduct overwrites lines in the batch files which
92 correspond to articles it has processed: the line is replaced with
93 one containing only spaces.  Only innd should create this file, and
94 only innduct should remove it.
95 .IP \fIfeedfile\fR_lock
96 .IX Item "lock file"
97 Lockfile, preventing multiple innduct invocations for the same
98 feed.  A process holds this lock after it has opened the lockfile,
99 made an fcntl F_SETLK call, and then checked with stat and fstat that
100 the file it now has open and has locked still has the name
101 \fIfeedfile\fR_lock.  (Only) the lockholder may delete the lockfile.
102 .IP \fIfeedfile\fR_flushing
103 .IX Item "flushing file"
104 Batch file: the main feedfile is renamed to this filename by innduct
105 before it asks inn to flush the feed.  Only innduct should create or
106 remove this file.
107 .IP \fIfeedfile\fR_defer
108 .IX Item "flushing file"
109 Batch file containing details of articles whose transmission has
110 recently been deferred at the request of the recipient site.  Created,
111 written, read and removed by innduct.
112 .IP \fIfeedfile\fR_backlog.\fItime_t\fR.\fIinum\fR
113 .IX Item "backlog file"
114 Batch file containing details of articles whose transmission has less
115 recently been deferred at the request of the recipient site.  Created
116 by innduct, and will also be read and removed by innduct.  However the
117 administrator may also safely remove backlog files.
118 .IP \fIfeedfile\fR_backlog\fIsomething\fR
119 .IX Item "manual backlog file"
120 Batch file manually provided by the administrator.  The file should be
121 complete and ready to process at the time it is renamed or hardlinked
122 to this name.  innduct will then automatically find and read and
123 process it and eventually remove it.  The administrator may also
124 safely remove backlog files.  \fIsomething\fR may not contain
125 \fB#\fR \fB~\fR or \fB/\fR.
126 .IP /etc/news/inn.conf
127 .IX Item inn.conf
128 Used to find
129 .IR pathoutgoing
130 if none is specified.
131 .SH HISTORY
132 Written by Ian Jackson <ijackson@chiark.greenend.org.uk>
133 .SH "SEE ALSO"
134 inn.conf(5),
135 newsfeeds(5)