chiark / gitweb /
Commit 2.4.5-5 as unpacked
[inn-innduct.git] / doc / man / innd.8
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings.  \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
32 .tr \(*W-
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 .    ds -- \(*W-
36 .    ds PI pi
37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
39 .    ds L" ""
40 .    ds R" ""
41 .    ds C` ""
42 .    ds C' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .if \nF \{\
56 .    de IX
57 .    tm Index:\\$1\t\\n%\t"\\$2"
58 ..
59 .    nr % 0
60 .    rr F
61 .\}
62 .\"
63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
65 .hy 0
66 .if n .na
67 .\"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
70 .    \" fudge factors for nroff and troff
71 .if n \{\
72 .    ds #H 0
73 .    ds #V .8m
74 .    ds #F .3m
75 .    ds #[ \f1
76 .    ds #] \fP
77 .\}
78 .if t \{\
79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 .    ds #V .6m
81 .    ds #F 0
82 .    ds #[ \&
83 .    ds #] \&
84 .\}
85 .    \" simple accents for nroff and troff
86 .if n \{\
87 .    ds ' \&
88 .    ds ` \&
89 .    ds ^ \&
90 .    ds , \&
91 .    ds ~ ~
92 .    ds /
93 .\}
94 .if t \{\
95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101 .\}
102 .    \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 .    \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 .    \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
117 \{\
118 .    ds : e
119 .    ds 8 ss
120 .    ds o a
121 .    ds d- d\h'-1'\(ga
122 .    ds D- D\h'-1'\(hy
123 .    ds th \o'bp'
124 .    ds Th \o'LP'
125 .    ds ae ae
126 .    ds Ae AE
127 .\}
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
130 .\"
131 .IX Title "INND 8"
132 .TH INND 8 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
133 .SH "NAME"
134 innd \- InterNetNews daemon
136 .IX Header "SYNOPSIS"
137 \&\fBinnd\fR [\fB\-aCdfNrsu\fR] [\fB\-c\fR \fIdays\fR] [\fB\-H\fR \fIcount\fR] [\fB\-i\fR \fIcount\fR]
138 [\fB\-I\fR \fIaddress\fR] [\fB\-l\fR \fIsize\fR] [\fB\-m\fR \fImode\fR] [\fB\-n\fR \fIflag\fR]
139 [\fB\-o\fR \fIcount\fR] [\fB\-p\fR \fIfd\fR] [\fB\-P\fR \fIport\fR] [\fB\-t\fR \fItimeout\fR]
140 [\fB\-T\fR \fIcount\fR] [\fB\-X\fR \fIseconds\fR]
142 .IX Header "DESCRIPTION"
143 \&\fBinnd\fR, the InterNetNews daemon, handles all incoming \s-1NNTP\s0 feeds,
144 coordinates the storage, retransmission, and overview generation for all
145 accepted articles, and manages the \fIactive\fR\|(5) and \fIhistory\fR\|(5) databases.  It
146 handles incoming connections on the \s-1NNTP\s0 port, and also creates and
147 listens to a local Unix-domain stream socket in order to receive articles
148 from local processes such as \fInnrpd\fR\|(8) and \fIrnews\fR\|(1).
149 .PP
150 As the master daemon, \fBinnd\fR should generally be started at boot and be
151 always running.  It listens to a Unix-domain datagram socket for commands
152 to control its activites, commands that can be sent using \fIctlinnd\fR\|(8).  The
153 current status of \fBinnd\fR can be obtained by running \f(CW\*(C`ctlinnd mode\*(C'\fR, or
154 for more detailed output, \fIinnstat\fR\|(8).
155 .PP
156 \&\fBinnd\fR can be in one of three operating modes:  running, paused, or
157 throttled.  Running is the normal mode; when the server is throttled, it
158 closes connections and rejects new ones.  Paused is like a temporary
159 throttle, suspending \fBinnd\fR's activities but not causing the server to
160 shut down existing connections.  The mode is normally changed via
161 \&\fIctlinnd\fR\|(8), either by various automated processes (such as nightly article
162 expiration) or manually by the news administrator, but \fBinnd\fR will also
163 throttle itself if it encounters \s-1ENOSPC\s0 errors in writing data or an
164 excessive number of I/O errors (among other problems).
165 .PP
166 \&\fBinnd\fR normally takes care of spawning \fInnrpd\fR\|(8) to handle connections
167 from news reading clients, but it can be run on a separate port from
168 \&\fInnrpd\fR\|(8) so that feed connections and news reading connections are handled
169 separately (this can often be faster).  Normally, \fBinnd\fR listens on port
170 119, the assigned port for \s-1NNTP\s0; if it is desireable to run \fBinnd\fR and
171 \&\fInnrpd\fR\|(8) on separate ports, it's recommended that \fInnrpd\fR\|(8) be given port
172 119 (since many news reading clients connect only to that port) and that
173 port 433 be used for \fBinnd\fR.
174 .PP
175 The primary configuration files that control \fBinnd\fR's activities are
176 \&\fIincoming.conf\fR, which specifies what remote sites \fBinnd\fR will accept
177 connections from, \fInewsfeeds\fR, which specifies what is to be done with
178 incoming articles besides storing them, and \fIinn.conf\fR, which sets a wide
179 variety of configuration parameters.  Some parameters in \fIinn.conf\fR\|(5) can
180 also be set with command-line flags; for these, the command-line flags
181 take precedence if used.
182 .PP
183 \&\fBinnd\fR should normally not run directly.  It must run as the news user or
184 all sorts of file ownership problems may result, and normally the port it
185 listens on (119 or 433) is privileged and must be opened by root.
186 Instead, \fBinnd\fR should normally be started via \fIinndstart\fR\|(8), a small
187 setuid-root program that opens the appropriate port, cleans up the
188 environment, changes to the news user, and then runs \fBinnd\fR, passing
189 along any command-line arguments.
190 .PP
191 To use IPv6, \fBinnd\fR must be started by \fBinndstart\fR.
193 .IX Header "OPTIONS"
194 For the options below that override \fIinn.conf\fR settings, see \fIinn.conf\fR\|(5)
195 for the default values if neither the \fIinn.conf\fR setting nor the
196 command-line option is given.
197 .IP "\fB\-a\fR" 4
198 .IX Item "-a"
199 By default, if a host connects to \fBinnd\fR but is not listed in
200 \&\fIincoming.conf\fR, the connection is handed off to \fBnnrpd\fR (or rejected if
201 \&\fInoreader\fR is set in \fIinn.conf\fR).  If \fB\-a\fR is given, \fIincoming.conf\fR
202 is ignored and any host can connect and transfer articles.  This flag
203 should never be used with an accessible server connected to Usenet; it
204 would open the server up for all sorts of abuse.
205 .IP "\fB\-c\fR \fIdays\fR" 4
206 .IX Item "-c days"
207 \&\fBinnd\fR normally rejects any article that is older (in days) than the
208 value of \fIartcutoff\fR in \fIinn.conf\fR.  This option, if given, overrides
209 the value of that setting.  If \fIdays\fR is 0, this check is suppressed and
210 \&\fBinnd\fR will accept articles regardless of how old they are.
211 .IP "\fB\-C\fR" 4
212 .IX Item "-C"
213 This flag tells \fBinnd\fR to accept and propagate but not actually process
214 cancel or supersede messages.  This is intended for sites concerned about
215 abuse of cancels, or that wish to use another cancel mechanism with
216 stronger authentication.
217 .IP "\fB\-d\fR, \fB\-f\fR" 4
218 .IX Item "-d, -f"
219 \&\fBinnd\fR normally puts itself into the background, points its standard
220 output and error to log files, and disassociates itself from the
221 terminal.  Using \fB\-d\fR prevents all of this, resulting in log messages
222 being written to standard output; this is generally useful only for
223 debugging.  Using \fB\-f\fR prevents the backgrounding and disassociation but
224 still redirects output; it may be useful if you want to monitor \fBinnd\fR
225 with a program that would be confused by forks.
226 .IP "\fB\-H\fR \fIcount\fR, \fB\-T\fR \fIcount\fR, \fB\-X\fR \fIseconds\fR" 4
227 .IX Item "-H count, -T count, -X seconds"
228 These flags control the number of connections per minute that are allowed.
229 This code is meant to protect your server from newsreader clients that
230 make too many connections per minute (and therefore these flags are
231 probably only useful when \fBinnd\fR is spawning \fBnnrpd\fR).  You probably
232 should not use these options unless you're having problems.  The table
233 used for this check is fixed at 128 entries and is used as a ring; the
234 size was chosen to make calculating the index easy and to be fairly sure
235 that it won't run out of space.  In practice, it is unlikely that even
236 half the table will be used at any given moment.
237 .Sp
238 The \fB\-H\fR flag limits the number of times a host is allowed to connect to
239 the server per the time interval given by \fB\-X\fR.  The default is \f(CW2\fR.
240 .Sp
241 The \fB\-T\fR flag limits the total number of incoming connections per the
242 time interval given by \fB\-X\fR.  The maximum value is \f(CW128\fR, and the
243 default is \f(CW60\fR.
244 .IP "\fB\-i\fR \fIcount\fR" 4
245 .IX Item "-i count"
246 \&\fBinnd\fR normally allows a maximum number of concurrent \s-1NNTP\s0 connections
247 given by the value of \fImaxconnections\fR in \fIinn.conf\fR.  This option, if
248 given, overrides the value of that setting.  If \fIcount\fR is \f(CW0\fR, this
249 check is suppressed.
250 .IP "\fB\-I\fR \fIaddress\fR" 4
251 .IX Item "-I address"
252 Normally if \fBinnd\fR itself binds to a port, it lets the operating system
253 pick the source \s-1IP\s0 address (unless \fIbindaddress\fR is set in \fIinn.conf\fR).
254 If this option is given, it specifies the \s-1IP\s0 address that \s-1INN\s0 should bind
255 as.  This is only relevant for servers with multiple local \s-1IP\s0 addresses.
256 The \s-1IP\s0 address must be in dotted quad (\f(CW\*(C`nnn.nnn.nnn.nnn\*(C'\fR) format.
257 .Sp
258 This option is rarely useful since \fBinnd\fR should not be binding to a
259 port itself.  Instead, use \fIinndstart\fR\|(8) and its analgous \fB\-I\fR option.
260 .IP "\fB\-l\fR \fIsize\fR" 4
261 .IX Item "-l size"
262 \&\fBinnd\fR normally rejects any article larger than the value of
263 \&\fImaxartsize\fR in \fIinn.conf\fR.  This option, if given, overrides the value
264 of that setting and specifies a maximum article size of \fIsize\fR.  If
265 \&\fIsize\fR is \f(CW0\fR, this check is suppressed.
266 .IP "\fB\-m\fR \fImode\fR" 4
267 .IX Item "-m mode"
268 Normally \fBinnd\fR starts in the \f(CW\*(C`running\*(C'\fR mode.  If this option is given,
269 it specifies what mode \fBinnd\fR should start in.  \fImode\fR should begin with
270 one of \f(CW\*(C`g\*(C'\fR, \f(CW\*(C`p\*(C'\fR, or \f(CW\*(C`t\*(C'\fR, and the starting mode will be set to
271 \&\f(CW\*(C`running\*(C'\fR, \f(CW\*(C`paused\*(C'\fR, or \f(CW\*(C`throttled\*(C'\fR, respectively, based on that
272 initial letter.  (\f(CW\*(C`g\*(C'\fR is short for \f(CW\*(C`go\*(C'\fR.)
273 .IP "\fB\-N\fR" 4
274 .IX Item "-N"
275 If this option is given, any filters (Perl, Tcl, or Python) are disabled
276 before \fBinnd\fR starts (normally, filters default to being enabled).  The
277 filters can be enabled after \fBinnd\fR has started with \fIctlinnd\fR\|(8).
278 .IP "\fB\-n\fR \fIflag\fR" 4
279 .IX Item "-n flag"
280 Whether \fBinnd\fR allows (and hands off to \fBnnrpd\fR) reader connections
281 while paused or throttled is normally determined by the value of
282 \&\fIreaderswhenstopped\fR in \fIinn.conf\fR).  This option, if given, overrides
283 that value.  If \fIflag\fR is \f(CW\*(C`n\*(C'\fR, \fBinnd\fR will not allow readers if it is
284 paused or throttled.  If \fIflag\fR is \f(CW\*(C`y\*(C'\fR, readers will be allowed
285 regardless of \fBinnd\fR's operating mode.
286 .IP "\fB\-o\fR \fIcount\fR" 4
287 .IX Item "-o count"
288 This flag limits the number of file descriptors that are available for
289 outgoing file feeds.  The default is the number of available file
290 descriptors minus some reserved for internal use (which could potentially
291 starve \fBinnd\fR of descriptors to use for accepting new connections).  If
292 \&\fBinnd\fR has more file feeds than \fIcount\fR, some of them will be buffered
293 and only written out periodically.
294 .Sp
295 Normally you never need to use this option, since the number of outgoing
296 feeds is fixed, being the number of file feeds configured in \fInewsfeeds\fR,
297 and is generally small (particularly given that \fIinnfeed\fR\|(8) is now used for
298 most outgoing feeds at large sites).
299 .IP "\fB\-p\fR \fIfd\fR" 4
300 .IX Item "-p fd"
301 If this flag is given, \fBinnd\fR expects the file descriptor given by \fIfd\fR
302 to already be open and bound to the appropriate local port and to be
303 suitable for listening to for incoming connections.  This is how
304 \&\fBinndstart\fR tells \fBinnd\fR which open file descriptor is the network
305 connection.  If this flag is not given, \fBinnd\fR will attempt to open its
306 network socket itself.  \fBinndstart\fR always passes this flag to \fBinnd\fR.
307 .IP "\fB\-P\fR \fIport\fR" 4
308 .IX Item "-P port"
309 The port \fBinnd\fR should listen on is normally given by the value of
310 \&\fIport\fR in \fIinn.conf\fR.  This option, if given, overrides that value and
311 specifies the port that \fBinnd\fR should bind to.  This option is rarely
312 useful since \fBinnd\fR normally does not bind itself; instead the analgous
313 \&\fB\-P\fR option to \fIinndstart\fR\|(8) should be used.  Since \fBinnd\fR should never
314 be run as root, \fIport\fR has to be a non-privileged port (one larger than
315 1024).
316 .IP "\fB\-r\fR" 4
317 .IX Item "-r"
318 Instructs \fBinnd\fR to renumber the \fIactive\fR file after starting, just as
319 if a \f(CW\*(C`ctlinnd renumber\*(C'\fR command were sent.
320 .IP "\fB\-s\fR" 4
321 .IX Item "-s"
322 Just check the syntax of the \fInewsfeeds\fR file and exit.  \fBinnd\fR will
323 exit with a non-zero status if any errors are found; the actual errors
324 will be reported via \fIsyslog\fR\|(3).
325 .IP "\fB\-t\fR \fIseconds\fR" 4
326 .IX Item "-t seconds"
327 Normally, \fBinnd\fR will flush any changes to history and the active file
328 after 300 seconds of inactivity.  This option changes that timeout to
329 \&\fIseconds\fR.
330 .IP "\fB\-u\fR" 4
331 .IX Item "-u"
332 The news log (the trace information for every article accepted by \fBinnd\fR)
333 is normally buffered.  This option changes the log to be unbuffered.
336 Arriving articles that have a Control: header are called \*(L"control
337 messages\*(R".  Except for cancel messages, these messages are handled by
338 \&\fIcontrolchan\fR\|(8) via a feed set up in \fInewsfeeds\fR.
339 .PP
340 (Cancel messages update the history database, so they must be handled
341 internally; the cost of syncing, locking, then unlocking would be too high
342 given the number of cancel messages that are received.  Note that if an
343 article is cancelled before it is received by the news server, it will
344 be rejected when it arrives since the history database has been updated;
345 it is useful for rejecting spam before it arrives.)
346 .PP
347 The distribution of control messages is different than that of standard
348 articles.  Control messages are normally filed into the pseudo-newsgroup
349 named \f(CW\*(C`control\*(C'\fR regardless of which newsgroup they were actually posted
350 to.  If, however, a \f(CW\*(C`control.\*(C'\fR\fIcommand\fR newsgroup exists that matches
351 the control command, the control message will be filed into that group
352 instead.  For example, a newgroup control message will be filed in
353 \&\f(CW\*(C`control.newgroup\*(C'\fR if that group exists; otherwise, it will be filed in
354 \&\f(CW\*(C`control\*(C'\fR.
355 .PP
356 If you want to specifically feed all control messages to a given site
357 regardless of whether the control messages would affect the newsgroups
358 you're feeding that site, you can put the appropriate control newsgroup in
359 the subscription list.  For example, to feed all cancel messages to a
360 given remote site (normally a bad idea), add \f(CW\*(C`control.cancel\*(C'\fR to its
361 subscription list.  Normally it's best to exclude the control newsgroups
362 from feeds to keep from sending your peers more control messages than they
363 care about.  That's why the \fInewsfeeds\fR pattern \f(CW\*(C`!control,!control.*\*(C'\fR
364 is as often as not specified (adding this pattern do not prevent control
365 messages which affect the newsgroups fed to a site from being sent to it).
366 .PP
367 checkgroups, newgroup and rmgroup control messages receive additional special
368 treatment.  If one of these control messages is approved and posted to the
369 newsgroup being created or removed (or to the admin group to which the
370 checkgroups is posted), the message will be sent to all sites
371 whose subscription patterns would cause them to receive articles posted to
372 that group.  For example, if a newgroup control message for a nonexistent
373 newsgroup \f(CW\*(C`news.admin.meow\*(C'\fR is received, it will be sent to any site
374 whose subscription pattern would cause it to receive \f(CW\*(C`news.admin.meow\*(C'\fR if
375 that newsgroup existed (such as a pattern of \f(CW\*(C`news.admin.*\*(C'\fR).  For this
376 reason, it is correct to post newgroup messages to the newsgroup that the
377 control message would create.  It is \fInot\fR generally correct to crosspost
378 newgroup messages to some \*(L"well\-propagated\*(R" newsgroup; not only will this
379 not actually improve their propagation to sites that want such control
380 messages, but it will also cause sites that do not want those control
381 messages to receive them.  Therefore, assuming that a newgroup control
382 message is sent to the group \f(CW\*(C`news.admin.meow\*(C'\fR (specified in the
383 Newsgroups: header) in order to create the group \f(CW\*(C`news.admin.meow\*(C'\fR,
384 the sites with the following subscription patterns will receive it:
385 .PP
386 .Vb 4
387 \&    *,@news.*
388 \&    news.*
389 \&    news.*,!control,!control.*
390 \&    control,control.*
391 .Ve
392 .PP
393 but the sites with the following subscription patterns will not receive it:
394 .PP
395 .Vb 2
396 \&    *,@news.*,!control,!control.*
397 \&    comp.*,@news.*
398 .Ve
399 .PP
400 If a control message is posted to a group whose name ends with the four
401 characters \f(CW\*(C`.ctl\*(C'\fR, this suffix is stripped off and the control message is
402 propagated as if it were posted to the base group.  For example, a cancel
403 message posted to \f(CW\*(C`news.admin.ctl\*(C'\fR will be sent to all sites that
404 subscribe to \f(CW\*(C`control.cancel\*(C'\fR (or \f(CW\*(C`control\*(C'\fR if that newsgroup doesn't
405 exist) or \f(CW\*(C`news.admin\*(C'\fR.  This behavior is present for historical
406 compatibility reasons and should be considered obsolete; support for the
407 \&\f(CW\*(C`.ctl\*(C'\fR suffix may be removed in a future version of \s-1INN\s0.
408 .PP
409 Finally, articles posted to newsgroups beginning with \f(CW\*(C`to.\*(C'\fR are treated
410 specially.  Provided that either that newsgroup exists in the \fIactive\fR file
411 or \fImergetogroups\fR is set in \fIinn.conf\fR, the remainder of the newsgroup
412 is taken to be a site name, as configured in \fInewsfeeds\fR, and the article
413 is sent to that site.  If \fImergetogroups\fR is set, the article will be
414 filed in the group named \f(CW\*(C`to\*(C'\fR (which must exist in the \fIactive\fR file).  For
415 example, with \fImergetogroups\fR set, an article posted to \f(CW\*(C`to.uunet\*(C'\fR will
416 be filed in \f(CW\*(C`to\*(C'\fR and sent to the site \f(CW\*(C`uunet\*(C'\fR.
419 \&\fBinnd\fR implements the \s-1NNTP\s0 commands defined in \s-1RFC\s0 977, with the
420 following differences:
421 .IP "1." 4
422 The \s-1LIST\s0 command may be followed by an optional \s-1ACTIVE\s0, \s-1ACTIVE\s0.TIMES, or
423 \&\s-1NEWSGROUPS\s0.  There is only basic support for \s-1LIST\s0 in \fBinnd\fR since feeding
424 peers normally don't need it; see \fInnrpd\fR\|(8) for full support.
425 .IP "2." 4
426 The \s-1AUTHINFO\s0 \s-1USER\s0 and \s-1AUTHINFO\s0 \s-1PASS\s0 commands are implemented, although the
427 authentication is currently limited to matching a password for a given
428 peer specified in \fIincoming.conf\fR.  These are based on the reference Unix
429 implementation.
430 .IP "3." 4
431 A new command, \s-1MODE\s0 \s-1READER\s0, is implemented.  This command will cause the
432 server to pass the connection to \fBnnrpd\fR.
433 .IP "4." 4
434 The streaming extension (\s-1MODE\s0 \s-1STREAM\s0, \s-1CHECK\s0, and \s-1TAKETHIS\s0) is fully
435 supported.
436 .IP "5." 4
437 A batch transfer command, \s-1XBATCH\s0 \fIbyte-count\fR, is provided.  This command
438 will read \fIbyte-count\fR bytes and store them for later processing by
439 \&\fIrnews\fR\|(1) (which must be run separately, probably from cron).  See
440 \&\fIinnxbatch\fR\|(8) and \fIbackends/sendxbatches\fR for more details on this
441 extension.
442 .IP "6." 4
443 \&\fBinnd\fR implements a limited subset of the protocol useful for
444 transferring news.  The only other commands implemented are \s-1HEAD\s0, \s-1HELP\s0,
445 \&\s-1IHAVE\s0, \s-1STAT\s0, and \s-1QUIT\s0.  The remaining commands are mostly only useful for
446 readers and are implemented by \fInnrpd\fR\|(8).
449 \&\fBinnd\fR modifies as few article headers as possible, although it could be
450 better in this area.
451 .PP
452 Empty headers and headers that consist of nothing but whitespace are
453 dropped.
454 .PP
455 The local site's name (as set with the \fIpathhost\fR parameter in
456 \&\fIinn.conf\fR) and an exclamation point are prepended to the Path: header,
457 provided the first site name in the Path: header is different from the
458 local one.  In addition, \fIpathalias\fR and \fIpathcluster\fR may be similarly
459 respectively prepended and appended to the Path: header; see \fIinn.conf\fR\|(5)
460 for the details.
461 .PP
462 The Xref: header is removed and a new one created.
463 .PP
464 A Lines: header will be added if the article was missing one.
465 .PP
466 \&\fBinnd\fR does not rewrite incorrect headers.  For example, it will not
467 replace an incorrect Lines header, though it may reject such an article
468 depending on the value of \fIlinecountfuzz\fR in \fIinn.conf\fR.
470 .IX Header "CANCEL FEEDS"
471 In order to efficiently apply a large number of local cancels (such as
472 from processing NoCeMs or from some other external source), \s-1INN\s0 supports a
473 special feed mode available only to connections to the local Unix domain
474 socket (not to connections to any network sockets).
475 .PP
476 To enter this mode, connect to the Unix domain socket (\fIpathrun\fR/nntpin)
477 and send the command \s-1MODE\s0 \s-1CANCEL\s0.  The response will have code \f(CW284\fR.
478 Every subsequent line sent on that connection should consist of a single
479 message \s-1ID\s0.  An attempt will be made to cancel that message \s-1ID\s0, and the
480 server will reply \f(CW289\fR for success or \f(CW484\fR for failure.  (Failure can
481 occur, for example, if the server is paused or throttled, or the
482 Message-ID is corrupt.  Failure does \fInot\fR occur if the article to be
483 cancelled does not exist.)
485 .IX Header "LOGGING"
486 \&\fBinnd\fR reports all incoming articles in its log file (\fIpathlog\fR/news).
487 This is a text file with a variable number of space-separated fields in
488 one of the following formats:
489 .PP
490 .Vb 5
491 \&    mon dd hh:mm:ss.mmm + feed <message\-id> site ...
492 \&    mon dd hh:mm:ss.mmm j feed <message\-id> site ...
493 \&    mon dd hh:mm:ss.mmm c feed <message\-id> Cancelling <message\-id>
494 \&    mon dd hh:mm:ss.mmm \- feed <message\-id> reason
495 \&    mon dd hh:mm:ss.mmm ? feed <message\-id> reason
496 .Ve
497 .PP
498 There may also be hostname and/or size fields after the message \s-1ID\s0
499 depending on the settings of \fInntplinklog\fR and \fIlogartsize\fR in
500 \&\fIinn.conf\fR.
501 .PP
502 The first three fields are the date and time to millisecond resolution.
503 The fifth field is the site that sent the article (based on the Path
504 header) and the sixth field is the article's message \s-1ID\s0; they will be a
505 question mark if the information is not available.
506 .PP
507 The fourth field indicates whether the article was accepted or not.  If it
508 is a plus sign, then the article was accepted.  If it is the letter \f(CW\*(C`j\*(C'\fR
509 then the article was accepted, but all of the newsgroups to which the
510 article was posted were set to mode \f(CW\*(C`j\*(C'\fR in the active file (or not listed
511 in the active file and \fIwanttrash\fR was set in \fIinn.conf\fR) so the article
512 was filed into the \f(CW\*(C`junk\*(C'\fR newsgroup.  In both of these cases, the article
513 has been accepted and the \f(CW\*(C`site ...\*(C'\fR field contains the space-separated
514 list of sites to which the article is being sent.
515 .PP
516 If the fourth field is the letter \f(CW\*(C`c\*(C'\fR, then a cancel message was accepted
517 before the original article arrived, and a history entry for the cancelled
518 message was created so that \fBinnd\fR will reject that message if it arrives
519 later.
520 .PP
521 If the fourth field is a minus sign, then the article was rejected.  The
522 reasons for rejection generated by \fBinnd\fR include:
523 .PP
524 .Vb 20
525 \&    "%s" header too long
526 \&    "%s" wants to cancel <%s> by "%s"
527 \&    Article exceeds local limit of %s bytes
528 \&    Article posted in the future \-\- "%s"
529 \&    Bad "%s" header
530 \&    Can't write history
531 \&    Duplicate
532 \&    Duplicate "%s" header
533 \&    EOF in headers
534 \&    Linecount %s != %s +\- %s
535 \&    Missing %s header
536 \&    No body
537 \&    No colon\-space in "%s" header
538 \&    No space
539 \&    Space before colon in "%s" header
540 \&    Too old \-\- "%s"
541 \&    Unapproved for "%s"
542 \&    Unwanted newsgroup "%s"
543 \&    Unwanted distribution "%s"
544 \&    Whitespace in "Newsgroups" header \-\- "%s"
545 .Ve
546 .PP
547 where \f(CW%s\fR, above, is replaced by more specific information.  (The Perl,
548 Python, andr Tcl filters, if used, may reject articles with other
549 reasons.)
550 .PP
551 If the fourth field is the letter \f(CW\*(C`?\*(C'\fR, the article contains strange
552 strings, such as \s-1CR\s0 without \s-1LF\s0 or \s-1LF\s0 without \s-1CR\s0.  (These characters should
553 never occur in isolation, only together as \s-1CRLF\s0 to indicate the end of a
554 line.)  This log message is just informational, to give an idea of how
555 widespread such articles are; \fBinnd\fR does not reject such articles.
556 .PP
557 Note that when \fIwanttrash\fR is set to true in \fIinn.conf\fR and an article
558 is received that isn't posted to any valid newsgroups, it will be accepted
559 and logged with two lines, a \f(CW\*(C`j\*(C'\fR line and a minus sign line.
560 .PP
561 \&\fBinnd\fR also makes extensive reports through \fIsyslog\fR\|(3).  The first word of
562 the log message will be the name of the site if the entry is site-specific
563 (such as a \*(L"connected\*(R" message).  The first word will be \f(CW\*(C`SERVER\*(C'\fR if the
564 message relates to the server itself, such as when a read error occurs.
565 .PP
566 If the second word is the four letters \f(CW\*(C`cant\*(C'\fR, then an error is being
567 reported.  (The absence of an apostrophe is intentional; it makes it
568 easier to grep from the command line and easier to find error messages in
569 FAQs using a search engine.)  In this case, the next two words generally
570 name the system call or library routine that failed and the object upon
571 which the action was being performed.  The rest of the line may contain
572 other information.
573 .PP
574 In other cases, the second word attempts to summarize what change has been
575 made, while the rest of the line gives more specific information.  The
576 word \f(CW\*(C`internal\*(C'\fR generally indicates an internal logic error.
578 .IX Header "SIGNALS"
579 \&\fBinnd\fR will catch \s-1SIGTERM\s0 and \s-1SIGHUP\s0 and shut down.  If \fB\-d\fR is used,
580 \&\s-1SIGINT\s0 will also be caught and will result in an orderly shutdown.
581 .PP
582 \&\fBinnd\fR will catch the \s-1SIGUSR1\s0 signal and recreate the control channel
583 used by \fIctlinnd\fR\|(8).
584 .SH "BUGS"
585 .IX Header "BUGS"
586 \&\fBinnd\fR normally attempts to strip \s-1IP\s0 options from incoming connections,
587 since it uses IP-based authentication and source routing can confuse that.
588 However, this doesn't work on all systems, and it doesn't work at all in
589 the presence of IPv6 support (and is disabled in that case).  Hence, if
590 using \fBinnd\fR with IPv6 support, make sure that your kernel or router
591 disables source routing.
593 .IX Header "HISTORY"
594 Written by Rich \f(CW$alz\fR <> for InterNetNews.
595 .PP
596 $Id: innd.8 7880 2008-06-16 20:37:13Z iulius $
597 .SH "SEE ALSO"
598 .IX Header "SEE ALSO"
599 \&\fIactive\fR\|(5), \fIctlinnd\fR\|(8), \fIdbz\fR\|(3), \fIhistory\fR\|(5), \fIincoming.conf\fR\|(5), \fIinn.conf\fR\|(5),
600 \&\fInewsfeeds\fR\|(5), \fInnrpd\fR\|(8), \fIrnews\fR\|(1), \fIsyslog\fR\|(3).