3 innd - InterNetNews daemon
7 B<innd> [B<-aCdfNrsu>] [B<-c> I<days>] [B<-H> I<count>] [B<-i> I<count>]
8 [B<-I> I<address>] [B<-l> I<size>] [B<-m> I<mode>] [B<-n> I<flag>]
9 [B<-o> I<count>] [B<-p> I<fd>] [B<-P> I<port>] [B<-t> I<timeout>]
10 [B<-T> I<count>] [B<-X> I<seconds>]
14 B<innd>, the InterNetNews daemon, handles all incoming NNTP feeds,
15 coordinates the storage, retransmission, and overview generation for all
16 accepted articles, and manages the active(5) and history(5) databases. It
17 handles incoming connections on the NNTP port, and also creates and
18 listens to a local Unix-domain stream socket in order to receive articles
19 from local processes such as nnrpd(8) and rnews(1).
21 As the master daemon, B<innd> should generally be started at boot and be
22 always running. It listens to a Unix-domain datagram socket for commands
23 to control its activites, commands that can be sent using ctlinnd(8). The
24 current status of B<innd> can be obtained by running C<ctlinnd mode>, or
25 for more detailed output, innstat(8).
27 B<innd> can be in one of three operating modes: running, paused, or
28 throttled. Running is the normal mode; when the server is throttled, it
29 closes connections and rejects new ones. Paused is like a temporary
30 throttle, suspending B<innd>'s activities but not causing the server to
31 shut down existing connections. The mode is normally changed via
32 ctlinnd(8), either by various automated processes (such as nightly article
33 expiration) or manually by the news administrator, but B<innd> will also
34 throttle itself if it encounters ENOSPC errors in writing data or an
35 excessive number of I/O errors (among other problems).
37 B<innd> normally takes care of spawning nnrpd(8) to handle connections
38 from news reading clients, but it can be run on a separate port from
39 nnrpd(8) so that feed connections and news reading connections are handled
40 separately (this can often be faster). Normally, B<innd> listens on port
41 119, the assigned port for NNTP; if it is desireable to run B<innd> and
42 nnrpd(8) on separate ports, it's recommended that nnrpd(8) be given port
43 119 (since many news reading clients connect only to that port) and that
44 port 433 be used for B<innd>.
46 The primary configuration files that control B<innd>'s activities are
47 F<incoming.conf>, which specifies what remote sites B<innd> will accept
48 connections from, F<newsfeeds>, which specifies what is to be done with
49 incoming articles besides storing them, and F<inn.conf>, which sets a wide
50 variety of configuration parameters. Some parameters in inn.conf(5) can
51 also be set with command-line flags; for these, the command-line flags
52 take precedence if used.
54 B<innd> should normally not run directly. It must run as the news user or
55 all sorts of file ownership problems may result, and normally the port it
56 listens on (119 or 433) is privileged and must be opened by root.
57 Instead, B<innd> should normally be started via inndstart(8), a small
58 setuid-root program that opens the appropriate port, cleans up the
59 environment, changes to the news user, and then runs B<innd>, passing
60 along any command-line arguments.
62 To use IPv6, B<innd> must be started by B<inndstart>.
66 For the options below that override F<inn.conf> settings, see inn.conf(5)
67 for the default values if neither the F<inn.conf> setting nor the
68 command-line option is given.
74 By default, if a host connects to B<innd> but is not listed in
75 F<incoming.conf>, the connection is handed off to B<nnrpd> (or rejected if
76 I<noreader> is set in F<inn.conf>). If B<-a> is given, F<incoming.conf>
77 is ignored and any host can connect and transfer articles. This flag
78 should never be used with an accessible server connected to Usenet; it
79 would open the server up for all sorts of abuse.
83 B<innd> normally rejects any article that is older (in days) than the
84 value of I<artcutoff> in F<inn.conf>. This option, if given, overrides
85 the value of that setting. If I<days> is 0, this check is suppressed and
86 B<innd> will accept articles regardless of how old they are.
90 This flag tells B<innd> to accept and propagate but not actually process
91 cancel or supersede messages. This is intended for sites concerned about
92 abuse of cancels, or that wish to use another cancel mechanism with
93 stronger authentication.
97 B<innd> normally puts itself into the background, points its standard
98 output and error to log files, and disassociates itself from the
99 terminal. Using B<-d> prevents all of this, resulting in log messages
100 being written to standard output; this is generally useful only for
101 debugging. Using B<-f> prevents the backgrounding and disassociation but
102 still redirects output; it may be useful if you want to monitor B<innd>
103 with a program that would be confused by forks.
105 =item B<-H> I<count>, B<-T> I<count>, B<-X> I<seconds>
107 These flags control the number of connections per minute that are allowed.
108 This code is meant to protect your server from newsreader clients that
109 make too many connections per minute (and therefore these flags are
110 probably only useful when B<innd> is spawning B<nnrpd>). You probably
111 should not use these options unless you're having problems. The table
112 used for this check is fixed at 128 entries and is used as a ring; the
113 size was chosen to make calculating the index easy and to be fairly sure
114 that it won't run out of space. In practice, it is unlikely that even
115 half the table will be used at any given moment.
117 The B<-H> flag limits the number of times a host is allowed to connect to
118 the server per the time interval given by B<-X>. The default is C<2>.
120 The B<-T> flag limits the total number of incoming connections per the
121 time interval given by B<-X>. The maximum value is C<128>, and the
126 B<innd> normally allows a maximum number of concurrent NNTP connections
127 given by the value of I<maxconnections> in F<inn.conf>. This option, if
128 given, overrides the value of that setting. If I<count> is C<0>, this
131 =item B<-I> I<address>
133 Normally if B<innd> itself binds to a port, it lets the operating system
134 pick the source IP address (unless I<bindaddress> is set in F<inn.conf>).
135 If this option is given, it specifies the IP address that INN should bind
136 as. This is only relevant for servers with multiple local IP addresses.
137 The IP address must be in dotted quad (C<nnn.nnn.nnn.nnn>) format.
139 This option is rarely useful since B<innd> should not be binding to a
140 port itself. Instead, use inndstart(8) and its analgous B<-I> option.
144 B<innd> normally rejects any article larger than the value of
145 I<maxartsize> in F<inn.conf>. This option, if given, overrides the value
146 of that setting and specifies a maximum article size of I<size>. If
147 I<size> is C<0>, this check is suppressed.
151 Normally B<innd> starts in the C<running> mode. If this option is given,
152 it specifies what mode B<innd> should start in. I<mode> should begin with
153 one of C<g>, C<p>, or C<t>, and the starting mode will be set to
154 C<running>, C<paused>, or C<throttled>, respectively, based on that
155 initial letter. (C<g> is short for C<go>.)
159 If this option is given, any filters (Perl, Tcl, or Python) are disabled
160 before B<innd> starts (normally, filters default to being enabled). The
161 filters can be enabled after B<innd> has started with ctlinnd(8).
165 Whether B<innd> allows (and hands off to B<nnrpd>) reader connections
166 while paused or throttled is normally determined by the value of
167 I<readerswhenstopped> in F<inn.conf>). This option, if given, overrides
168 that value. If I<flag> is C<n>, B<innd> will not allow readers if it is
169 paused or throttled. If I<flag> is C<y>, readers will be allowed
170 regardless of B<innd>'s operating mode.
174 This flag limits the number of file descriptors that are available for
175 outgoing file feeds. The default is the number of available file
176 descriptors minus some reserved for internal use (which could potentially
177 starve B<innd> of descriptors to use for accepting new connections). If
178 B<innd> has more file feeds than I<count>, some of them will be buffered
179 and only written out periodically.
181 Normally you never need to use this option, since the number of outgoing
182 feeds is fixed, being the number of file feeds configured in F<newsfeeds>,
183 and is generally small (particularly given that innfeed(8) is now used for
184 most outgoing feeds at large sites).
188 If this flag is given, B<innd> expects the file descriptor given by I<fd>
189 to already be open and bound to the appropriate local port and to be
190 suitable for listening to for incoming connections. This is how
191 B<inndstart> tells B<innd> which open file descriptor is the network
192 connection. If this flag is not given, B<innd> will attempt to open its
193 network socket itself. B<inndstart> always passes this flag to B<innd>.
197 The port B<innd> should listen on is normally given by the value of
198 I<port> in F<inn.conf>. This option, if given, overrides that value and
199 specifies the port that B<innd> should bind to. This option is rarely
200 useful since B<innd> normally does not bind itself; instead the analgous
201 B<-P> option to inndstart(8) should be used. Since B<innd> should never
202 be run as root, I<port> has to be a non-privileged port (one larger than
207 Instructs B<innd> to renumber the F<active> file after starting, just as
208 if a C<ctlinnd renumber> command were sent.
212 Just check the syntax of the F<newsfeeds> file and exit. B<innd> will
213 exit with a non-zero status if any errors are found; the actual errors
214 will be reported via syslog(3).
216 =item B<-t> I<seconds>
218 Normally, B<innd> will flush any changes to history and the active file
219 after 300 seconds of inactivity. This option changes that timeout to
224 The news log (the trace information for every article accepted by B<innd>)
225 is normally buffered. This option changes the log to be unbuffered.
229 =head1 CONTROL MESSAGES
231 Arriving articles that have a Control: header are called "control
232 messages". Except for cancel messages, these messages are handled by
233 controlchan(8) via a feed set up in F<newsfeeds>.
235 (Cancel messages update the history database, so they must be handled
236 internally; the cost of syncing, locking, then unlocking would be too high
237 given the number of cancel messages that are received. Note that if an
238 article is cancelled before it is received by the news server, it will
239 be rejected when it arrives since the history database has been updated;
240 it is useful for rejecting spam before it arrives.)
242 The distribution of control messages is different than that of standard
243 articles. Control messages are normally filed into the pseudo-newsgroup
244 named C<control> regardless of which newsgroup they were actually posted
245 to. If, however, a C<control.>I<command> newsgroup exists that matches
246 the control command, the control message will be filed into that group
247 instead. For example, a newgroup control message will be filed in
248 C<control.newgroup> if that group exists; otherwise, it will be filed in
251 If you want to specifically feed all control messages to a given site
252 regardless of whether the control messages would affect the newsgroups
253 you're feeding that site, you can put the appropriate control newsgroup in
254 the subscription list. For example, to feed all cancel messages to a
255 given remote site (normally a bad idea), add C<control.cancel> to its
256 subscription list. Normally it's best to exclude the control newsgroups
257 from feeds to keep from sending your peers more control messages than they
258 care about. That's why the F<newsfeeds> pattern C<!control,!control.*>
259 is as often as not specified (adding this pattern do not prevent control
260 messages which affect the newsgroups fed to a site from being sent to it).
262 checkgroups, newgroup and rmgroup control messages receive additional special
263 treatment. If one of these control messages is approved and posted to the
264 newsgroup being created or removed (or to the admin group to which the
265 checkgroups is posted), the message will be sent to all sites
266 whose subscription patterns would cause them to receive articles posted to
267 that group. For example, if a newgroup control message for a nonexistent
268 newsgroup C<news.admin.meow> is received, it will be sent to any site
269 whose subscription pattern would cause it to receive C<news.admin.meow> if
270 that newsgroup existed (such as a pattern of C<news.admin.*>). For this
271 reason, it is correct to post newgroup messages to the newsgroup that the
272 control message would create. It is I<not> generally correct to crosspost
273 newgroup messages to some "well-propagated" newsgroup; not only will this
274 not actually improve their propagation to sites that want such control
275 messages, but it will also cause sites that do not want those control
276 messages to receive them. Therefore, assuming that a newgroup control
277 message is sent to the group C<news.admin.meow> (specified in the
278 Newsgroups: header) in order to create the group C<news.admin.meow>,
279 the sites with the following subscription patterns will receive it:
283 news.*,!control,!control.*
286 but the sites with the following subscription patterns will not receive it:
288 *,@news.*,!control,!control.*
291 If a control message is posted to a group whose name ends with the four
292 characters C<.ctl>, this suffix is stripped off and the control message is
293 propagated as if it were posted to the base group. For example, a cancel
294 message posted to C<news.admin.ctl> will be sent to all sites that
295 subscribe to C<control.cancel> (or C<control> if that newsgroup doesn't
296 exist) or C<news.admin>. This behavior is present for historical
297 compatibility reasons and should be considered obsolete; support for the
298 C<.ctl> suffix may be removed in a future version of INN.
300 Finally, articles posted to newsgroups beginning with C<to.> are treated
301 specially. Provided that either that newsgroup exists in the F<active> file
302 or I<mergetogroups> is set in F<inn.conf>, the remainder of the newsgroup
303 is taken to be a site name, as configured in F<newsfeeds>, and the article
304 is sent to that site. If I<mergetogroups> is set, the article will be
305 filed in the group named C<to> (which must exist in the F<active> file). For
306 example, with I<mergetogroups> set, an article posted to C<to.uunet> will
307 be filed in C<to> and sent to the site C<uunet>.
309 =head1 PROTOCOL DIFFERENCES
311 B<innd> implements the NNTP commands defined in RFC 977, with the
312 following differences:
318 The LIST command may be followed by an optional ACTIVE, ACTIVE.TIMES, or
319 NEWSGROUPS. There is only basic support for LIST in B<innd> since feeding
320 peers normally don't need it; see nnrpd(8) for full support.
324 The AUTHINFO USER and AUTHINFO PASS commands are implemented, although the
325 authentication is currently limited to matching a password for a given
326 peer specified in F<incoming.conf>. These are based on the reference Unix
331 A new command, MODE READER, is implemented. This command will cause the
332 server to pass the connection to B<nnrpd>.
336 The streaming extension (MODE STREAM, CHECK, and TAKETHIS) is fully
341 A batch transfer command, XBATCH I<byte-count>, is provided. This command
342 will read I<byte-count> bytes and store them for later processing by
343 rnews(1) (which must be run separately, probably from cron). See
344 innxbatch(8) and F<backends/sendxbatches> for more details on this
349 B<innd> implements a limited subset of the protocol useful for
350 transferring news. The only other commands implemented are HEAD, HELP,
351 IHAVE, STAT, and QUIT. The remaining commands are mostly only useful for
352 readers and are implemented by nnrpd(8).
356 =head1 HEADER MODIFICATIONS
358 B<innd> modifies as few article headers as possible, although it could be
361 Empty headers and headers that consist of nothing but whitespace are
364 The local site's name (as set with the I<pathhost> parameter in
365 F<inn.conf>) and an exclamation point are prepended to the Path: header,
366 provided the first site name in the Path: header is different from the
367 local one. In addition, I<pathalias> and I<pathcluster> may be similarly
368 respectively prepended and appended to the Path: header; see inn.conf(5)
371 The Xref: header is removed and a new one created.
373 A Lines: header will be added if the article was missing one.
375 B<innd> does not rewrite incorrect headers. For example, it will not
376 replace an incorrect Lines header, though it may reject such an article
377 depending on the value of I<linecountfuzz> in F<inn.conf>.
381 In order to efficiently apply a large number of local cancels (such as
382 from processing NoCeMs or from some other external source), INN supports a
383 special feed mode available only to connections to the local Unix domain
384 socket (not to connections to any network sockets).
386 To enter this mode, connect to the Unix domain socket (I<pathrun>/nntpin)
387 and send the command MODE CANCEL. The response will have code C<284>.
388 Every subsequent line sent on that connection should consist of a single
389 message ID. An attempt will be made to cancel that message ID, and the
390 server will reply C<289> for success or C<484> for failure. (Failure can
391 occur, for example, if the server is paused or throttled, or the
392 Message-ID is corrupt. Failure does I<not> occur if the article to be
393 cancelled does not exist.)
397 B<innd> reports all incoming articles in its log file (I<pathlog>/news).
398 This is a text file with a variable number of space-separated fields in
399 one of the following formats:
401 mon dd hh:mm:ss.mmm + feed <message-id> site ...
402 mon dd hh:mm:ss.mmm j feed <message-id> site ...
403 mon dd hh:mm:ss.mmm c feed <message-id> Cancelling <message-id>
404 mon dd hh:mm:ss.mmm - feed <message-id> reason
405 mon dd hh:mm:ss.mmm ? feed <message-id> reason
407 There may also be hostname and/or size fields after the message ID
408 depending on the settings of I<nntplinklog> and I<logartsize> in
411 The first three fields are the date and time to millisecond resolution.
412 The fifth field is the site that sent the article (based on the Path
413 header) and the sixth field is the article's message ID; they will be a
414 question mark if the information is not available.
416 The fourth field indicates whether the article was accepted or not. If it
417 is a plus sign, then the article was accepted. If it is the letter C<j>
418 then the article was accepted, but all of the newsgroups to which the
419 article was posted were set to mode C<j> in the active file (or not listed
420 in the active file and I<wanttrash> was set in F<inn.conf>) so the article
421 was filed into the C<junk> newsgroup. In both of these cases, the article
422 has been accepted and the C<site ...> field contains the space-separated
423 list of sites to which the article is being sent.
425 If the fourth field is the letter C<c>, then a cancel message was accepted
426 before the original article arrived, and a history entry for the cancelled
427 message was created so that B<innd> will reject that message if it arrives
430 If the fourth field is a minus sign, then the article was rejected. The
431 reasons for rejection generated by B<innd> include:
434 "%s" wants to cancel <%s> by "%s"
435 Article exceeds local limit of %s bytes
436 Article posted in the future -- "%s"
440 Duplicate "%s" header
442 Linecount %s != %s +- %s
445 No colon-space in "%s" header
447 Space before colon in "%s" header
450 Unwanted newsgroup "%s"
451 Unwanted distribution "%s"
452 Whitespace in "Newsgroups" header -- "%s"
454 where C<%s>, above, is replaced by more specific information. (The Perl,
455 Python, andr Tcl filters, if used, may reject articles with other
458 If the fourth field is the letter C<?>, the article contains strange
459 strings, such as CR without LF or LF without CR. (These characters should
460 never occur in isolation, only together as CRLF to indicate the end of a
461 line.) This log message is just informational, to give an idea of how
462 widespread such articles are; B<innd> does not reject such articles.
464 Note that when I<wanttrash> is set to true in F<inn.conf> and an article
465 is received that isn't posted to any valid newsgroups, it will be accepted
466 and logged with two lines, a C<j> line and a minus sign line.
468 B<innd> also makes extensive reports through syslog(3). The first word of
469 the log message will be the name of the site if the entry is site-specific
470 (such as a "connected" message). The first word will be C<SERVER> if the
471 message relates to the server itself, such as when a read error occurs.
473 If the second word is the four letters C<cant>, then an error is being
474 reported. (The absence of an apostrophe is intentional; it makes it
475 easier to grep from the command line and easier to find error messages in
476 FAQs using a search engine.) In this case, the next two words generally
477 name the system call or library routine that failed and the object upon
478 which the action was being performed. The rest of the line may contain
481 In other cases, the second word attempts to summarize what change has been
482 made, while the rest of the line gives more specific information. The
483 word C<internal> generally indicates an internal logic error.
487 B<innd> will catch SIGTERM and SIGHUP and shut down. If B<-d> is used,
488 SIGINT will also be caught and will result in an orderly shutdown.
490 B<innd> will catch the SIGUSR1 signal and recreate the control channel
495 B<innd> normally attempts to strip IP options from incoming connections,
496 since it uses IP-based authentication and source routing can confuse that.
497 However, this doesn't work on all systems, and it doesn't work at all in
498 the presence of IPv6 support (and is disabled in that case). Hence, if
499 using B<innd> with IPv6 support, make sure that your kernel or router
500 disables source routing.
504 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
506 $Id: innd.pod 7748 2008-04-06 13:49:56Z iulius $
510 active(5), ctlinnd(8), dbz(3), history(5), incoming.conf(5), inn.conf(5),
511 newsfeeds(5), nnrpd(8), rnews(1), syslog(3).