1INND(8) InterNetNews Documentation INND(8)
2
6 innd - InterNetNews daemon
7
9 innd [-adfNrsSu] [-4 address] [-6 address] [-c days] [-H count] [-i
10 count] [-l size] [-m mode] [-n flag] [-o count] [-P port] [-t timeout]
11 [-T count] [-X seconds]
12
14 innd, the InterNetNews daemon, handles all incoming NNTP feeds,
15 coordinates the storage, retransmission, and overview generation for
16 all accepted articles, and manages the active(5) and history(5)
17 databases. It handles incoming connections on the NNTP port, and also
18 creates and listens to a local Unix-domain stream socket in order to
19 receive articles from local processes such as nnrpd(8) and rnews(1).
20 As the master daemon, innd should generally be started at boot and be
22 always running. It listens to a Unix-domain datagram socket for
23 commands to control its activities, commands that can be sent using
24 ctlinnd(8). The current status of innd can be obtained by running
25 "ctlinnd mode", or for more detailed output, innstat(8).
26 innd can be in one of three operating modes: running, paused, or
28 throttled. Running is the normal mode; when the server is throttled,
29 it closes connections and rejects new ones. Paused is like a temporary
30 throttle, suspending 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
33 article expiration) or manually by the news administrator, but innd
34 will also throttle itself if it encounters ENOSPC errors in writing
35 data or an excessive number of I/O errors (among other problems).
36 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
40 handled separately (this can often be faster). Normally, innd listens
41 on port 119, the assigned port for NNTP; if it is desirable to run innd
42 and nnrpd(8) on separate ports, it's recommended that nnrpd(8) be given
43 port 119 (since many news reading clients connect only to that port)
44 and that port 433 be used for innd.
45 The primary configuration files that control innd's activities are
47 incoming.conf, which specifies what remote sites innd will accept
48 connections from, newsfeeds, which specifies what is to be done with
49 incoming articles besides storing them, and inn.conf, which sets a wide
50 variety of configuration parameters. Some parameters in inn.conf(5)
51 can also be set with command-line flags; for these, the command-line
52 flags take precedence if used.
53 innd must be run as the news user and news group. It will check for
55 this at startup and fail to start if not run properly. Normally it
56 should be started via rc.news(8) as part of the system boot up process.
57 It relies on the setuid root helper program innbind(8) to listen on a
58 privileged port (119, 433 or 563).
59
61 For the options below that override inn.conf settings, see inn.conf(5)
62 for the default values if neither the inn.conf setting nor the command-
63 line option is given.
64 -4 address
66 Normally, innd binds to all local IP addresses (unless bindaddress
67 is set in inn.conf). If this option is given, it specifies the IP
68 address that INN should bind as. This is only relevant for servers
69 with multiple local IP addresses. The IP address must be in
70 dotted-quad ("nnn.nnn.nnn.nnn") format.
71 If this option is specified, it's the same as setting bindaddress
73 in inn.conf and may cause changes in whether INN binds to an IPv6
74 address as well. See inn.conf(5) for more details and also the -6
75 flag for innd.
76 This option has no effect when systemd socket activation is used.
78 -6 address
80 Only applies when INN has been built with IPv6 support. Normally
81 innd binds to all local IP addresses (unless bindaddress6 is set in
82 inn.conf). If this option is given, it specifies the IPv6 address
83 that INN should bind to. The IPv6 address must be in colon-
84 separated RFC 4291 format ("n:n:n:n:n:n:n:n").
85 If this option is specified, it's the same as setting bindaddress6
87 in inn.conf and may cause changes in whether INN binds to an IPv4
88 address as well. See inn.conf(5) for more details and also the -4
89 flag for innd.
90 This option has no effect when systemd socket activation is used.
92 -a By default, if a host connects to innd but is not listed in
94 incoming.conf, the connection is handed off to nnrpd (or rejected
95 if noreader is set in inn.conf). If -a is given, incoming.conf is
96 ignored and any host can connect and transfer articles. This flag
97 should never be used with an accessible server connected to Usenet;
98 it would open the server up for all sorts of abuse.
99 -c days
101 innd normally rejects any article that is older (in days) than the
102 value of artcutoff in inn.conf. This option, if given, overrides
103 the value of that setting. If days is 0, this check is suppressed
104 and innd will accept articles regardless of how old they are.
105 Note that rejected articles are remembered during the number of
107 days specified by the "/remember/" line in expire.ctl(5). You'll
108 have to wait that number of days before being able to inject again
109 an article with the same previously rejected Message-ID.
110 In case you need re-injecting articles before that amount of time,
112 you'll have to set "/remember/" to 0 in expire.ctl, run the expire
113 process (for instance via news.daily called with the same
114 parameters as in crontab, plus "notdaily") and undo the change in
115 expire.ctl. All previously rejected or removed articles will then
116 not be considered as duplicate if their Message-ID is proposed.
117 -d, -f
119 innd normally puts itself into the background, points its standard
120 output and error to log files, and disassociates itself from the
121 terminal. Using -d prevents all of this, resulting in log messages
122 being written to standard output; this is generally useful only for
123 debugging. Using -f prevents the backgrounding and disassociation
124 but still redirects output; it may be useful if you want to monitor
125 innd with a program that would be confused by forks.
126 -H count, -T count, -X seconds
128 These flags control the number of connections per seconds seconds
129 that are allowed. This code is meant to protect your server from
130 newsreader clients that make too many connections per minute (and
131 therefore these flags are probably only useful when innd is
132 spawning nnrpd). You probably should not use these options unless
133 you're having problems. The table used for this check is fixed at
134 128 entries and is used as a ring; the size was chosen to make
135 calculating the index easy and to be fairly sure that it won't run
136 out of space. In practice, it is unlikely that even half the table
137 will be used at any given moment.
138 The -H flag limits the number of times a host is allowed to connect
140 to the server per the time interval given by -X. The default is 2.
141 The -T flag limits the total number of incoming connections per the
143 time interval given by -X. The maximum value is 128, and the
144 default is 60.
145 Note that the time interval given by -X is set to 0 by default,
147 that is to say no control is done on the number of connections.
148 -i count
150 innd normally allows a maximum number of concurrent NNTP
151 connections given by the value of maxconnections in inn.conf. This
152 option, if given, overrides the value of that setting. If count is
153 0, this check is suppressed.
154 -l size
156 innd normally rejects any article larger than the value of
157 maxartsize in inn.conf. This option, if given, overrides the value
158 of that setting and specifies a maximum article size of size. If
159 size is 0, this check is suppressed.
160 -m mode
162 Normally, innd starts in the "running" mode. If this option is
163 given, it specifies what mode innd should start in. mode should
164 begin with one of "g", "p", or "t", and the starting mode will be
165 set to "running", "paused", or "throttled", respectively, based on
166 that initial letter. ("g" is short for "go".)
167 -N If this option is given, any filters (Perl or Python) are disabled
169 before innd starts (normally, filters default to being enabled).
170 The filters can be enabled after innd has started with ctlinnd(8).
171 -n flag
173 Whether innd allows (and hands off to nnrpd) reader connections
174 while paused or throttled is normally determined by the value of
175 readerswhenstopped in inn.conf. This option, if given, overrides
176 that value. If flag is "n", innd will not allow readers if it is
177 paused or throttled. If flag is "y", readers will be allowed
178 regardless of innd's operating mode.
179 -o count
181 This flag limits the number of file descriptors that are available
182 for outgoing file feeds. The default is the number of available
183 file descriptors minus some reserved for internal use (which could
184 potentially starve innd of descriptors to use for accepting new
185 connections). If innd has more file feeds than count, some of them
186 will be buffered and only written out periodically.
187 Normally you never need to use this option, since the number of
189 outgoing feeds is fixed, being the number of file feeds configured
190 in newsfeeds, and is generally small (particularly given that
191 innfeed(8) is now used for most outgoing feeds at large sites).
192 -P port
194 The port innd should listen on is normally given by the value of
195 port in inn.conf. This option, if given, overrides that value and
196 specifies the port that innd should bind to.
197 -r Instructs innd to renumber the active file after starting, just as
199 if a "ctlinnd renumber" command were sent.
200 -s Just check the syntax of the newsfeeds file and exit. innd will
202 exit with a non-zero status if any errors are found; the actual
203 errors will be reported via syslog(3).
204 -S Report errors found in incoming.conf via syslog(3) and exit
206 normally. (Yes, this is less useful than it should be.)
207 -t seconds
209 Normally, innd will flush any changes to history and the active
210 file after 300 seconds of inactivity. This option changes that
211 timeout to seconds.
212 -u The news log (the trace information for every article accepted by
214 innd) is normally buffered. This option changes the log to be
215 unbuffered.
216
218 Arriving articles that have a Control header field are called "control
219 messages". Except for cancel messages, these messages are handled by
220 controlchan(8) via a feed set up in newsfeeds.
221 (Cancel messages update the history database, so they must be handled
223 internally; the cost of syncing, locking, then unlocking would be too
224 high given the number of cancel messages that are received. Note that
225 if an article is cancelled before it is received by the news server, it
226 will be rejected when it arrives since the history database has been
227 updated; it is useful for rejecting spam before it arrives.)
228 The distribution of control messages is different than that of standard
230 articles. Control messages are normally filed into the pseudo-
231 newsgroup named "control" regardless of which newsgroup they were
232 actually posted to. If, however, a "control."command newsgroup exists
233 that matches the control command, the control message will be filed
234 into that group instead. For example, a newgroup control message will
235 be filed in "control.newgroup" if that group exists; otherwise, it will
236 be filed in "control".
237 If you want to specifically feed all control messages to a given site
239 regardless of whether the control messages would affect the newsgroups
240 you're feeding that site, you can put the appropriate control newsgroup
241 in the subscription list. For example, to feed all cancel messages to
242 a given remote site (normally a bad idea), add "control.cancel" to its
243 subscription list. Normally it's best to exclude the control
244 newsgroups from feeds to keep from sending your peers more control
245 messages than they care about. That's why the newsfeeds pattern
246 "!control,!control.*" is as often as not specified (adding this
247 pattern do not prevent control messages which affect the newsgroups fed
248 to a site from being sent to it).
249 checkgroups, newgroup and rmgroup control messages receive additional
251 special treatment. If one of these control messages is approved and
252 posted to the newsgroup being created or removed (or to the admin group
253 to which the checkgroups is posted), the message will be sent to all
254 sites whose subscription patterns would cause them to receive articles
255 posted to that group. For example, if a newgroup control message for a
256 nonexistent newsgroup "news.admin.meow" is received, it will be sent to
257 any site whose subscription pattern would cause it to receive
258 "news.admin.meow" if that newsgroup existed (such as a pattern of
259 "news.admin.*"). For this reason, it is correct to post newgroup
260 messages to the newsgroup that the control message would create. It is
261 not generally correct to crosspost newgroup messages to some "well-
262 propagated" newsgroup; not only will this not actually improve their
263 propagation to sites that want such control messages, but it will also
264 cause sites that do not want those control messages to receive them.
265 Therefore, assuming that a newgroup control message is sent to the
266 group "news.admin.meow" (specified in the Newsgroups header field body)
267 in order to create the group "news.admin.meow", the sites with the
268 following subscription patterns will receive it:
269 *,@news.*
271 news.*
272 news.*,!control,!control.*
273 control,control.*
274 As a matter of fact, for the first pattern, "control.newgroup" (or
276 "control") is included in "*". However, the sites with the following
277 subscription patterns will not receive it:
278 *,@news.*,!control,!control.*
280 comp.*,@news.*
281 If a control message is posted to a group whose name ends with the four
283 characters ".ctl", this suffix is stripped off and the control message
284 is propagated as if it were posted to the base group. For example, a
285 cancel message posted to "news.admin.ctl" will be sent to all sites
286 that subscribe to "control.cancel" (or "control" if that newsgroup
287 doesn't exist) or "news.admin". This behavior is present for
288 historical compatibility reasons and should be considered obsolete;
289 support for the ".ctl" suffix may be removed in a future version of
290 INN.
291 Finally, articles posted to newsgroups beginning with "to." are treated
293 specially. Provided that either that newsgroup exists in the active
294 file or mergetogroups is set in inn.conf, the remainder of the
295 newsgroup is taken to be a site name, as configured in newsfeeds, and
296 the article is sent to sites propagating "to.uunet". If mergetogroups
297 is set, the article will be filed in the group named "to" (which must
298 exist in the active file). For example, with mergetogroups set, an
299 article posted to "to.uunet" will be filed in "to" and sent to the
300 sites propagating "to.uunet".
301
303 innd implements the NNTP commands defined in RFC 3977 (NNTP), RFC 4643
304 (NNTP authentication), RFC 4644 (streaming NNTP feeds) and RFC 6048
305 (NNTP LIST additions) with the following differences:
306 1. A batch transfer command, XBATCH byte-count, is provided. This
308 command will read byte-count bytes and store them for later
309 processing by rnews(1) (which must be run separately, probably from
310 cron). See innxbatch(8) and sendxbatches for more details on this
311 extension.
312 2. As INN is a mode-switching news server, innd implements a limited
314 subset of the protocol useful for transferring news. The remaining
315 commands are mostly only useful for readers and are implemented by
316 nnrpd(8). Use of the MODE READER command will cause innd to pass
317 the connection to nnrpd.
318 3. innd allows a wider syntax for wildmats.
320 4. Three commands (IHAVE, CHECK and TAKETHIS) will continue, for
322 interoperability reasons, to return a reject code (respectively
323 435, 438 and 439) when the command contains a syntax error (which
324 normally leads to 501).
325
327 innd modifies as few article headers as possible, although it could be
328 better in this area.
329 Empty header field bodies and header field bodies that consist of
331 nothing but whitespace are dropped.
332 The local site's name (as set with the pathhost parameter in inn.conf)
334 and an exclamation point are prepended to the Path header field body,
335 provided the first site name in the Path header field body is different
336 from the local one. In addition, pathalias and pathcluster may be
337 similarly respectively prepended and appended as path identities
338 immediately to the right or the left of pathhost in the Path header
339 field body; see inn.conf(5) for the details.
340 The Xref header field is removed and a new one created.
342 innd does not rewrite incorrect header fields. For example, it will
344 not replace an incorrect Lines header field, though it may reject such
345 an article depending on the value of linecountfuzz in inn.conf.
346
348 In order to efficiently apply a large number of local cancels (such as
349 from processing NoCeMs or from some other external source), INN
350 supports a special feed mode available only to connections to the local
351 Unix-domain socket (not to connections to any network sockets).
352 To enter this mode, connect to the Unix-domain socket (pathrun/nntpin)
354 and send the command MODE CANCEL. The response will have code 284.
355 Every subsequent line sent on that connection should consist of a
356 single message-ID. An attempt will be made to cancel that message-ID,
357 and the server will reply 289 for success or 484 for failure. (Failure
358 can occur, for example, if the server is paused or throttled, or the
359 message-ID is corrupt. Failure does not occur if the article to be
360 cancelled does not exist.)
361
363 innd reports all incoming articles in its log file (pathlog/news).
364 This is a text file with a variable number of space-separated fields in
365 one of the following formats:
366 mon dd hh:mm:ss.mmm + feed <message-id> site ...
368 mon dd hh:mm:ss.mmm j feed <message-id> site ...
369 mon dd hh:mm:ss.mmm c feed <message-id> Cancelling <message-id>
370 mon dd hh:mm:ss.mmm - feed <message-id> reason
371 mon dd hh:mm:ss.mmm ? feed <message-id> reason
372 There may also be hostname and/or size fields after the message-ID
374 depending on the settings of nntplinklog and logartsize in inn.conf.
375 The first three fields are the date and time to millisecond resolution.
377 The fifth field is the site that sent the article (based on the Path
378 header field body) and the sixth field is the article's Message-ID;
379 they will be a question mark if the information is not available.
380 The fourth field indicates whether the article was accepted or not. If
382 it is a plus sign, then the article was accepted. If it is the letter
383 "j", then the article was accepted, providing all of the newsgroups to
384 which the article was posted were set to status "j" in the active file
385 (or not listed in the active file and wanttrash was set in inn.conf),
386 and then the article was filed into the "junk" newsgroup. In both of
387 these cases, the article has been accepted and the "site ..." field
388 contains the space-separated list of sites to which the article is
389 being sent.
390 If the fourth field is the letter "c", then a cancel message was
392 accepted before the original article arrived, and a history entry for
393 the cancelled message was created so that innd will reject that message
394 if it arrives later.
395 If the fourth field is a minus sign, then the article was rejected.
397 The reasons for rejection generated by innd include:
398 "%s" header too long
400 Article exceeds local limit of %s bytes
401 Article posted in the future -- "%s"
402 Bad "%s" header field
403 Can't write history
404 Duplicate
405 Duplicate "%s" header field
406 EOF in headers
407 Linecount %s != %s +- %s
408 Missing %s header field
409 No body
410 No colon-space in "%s" header field
411 No matching newsgroups in cancel <%s>
412 No space
413 Space before colon in "%s" header field
414 Too old -- "%s"
415 Unapproved for "%s"
416 Unwanted newsgroup "%s"
417 Unwanted distribution "%s"
418 Whitespace in "Newsgroups" header field -- "%s"
419 where %s, above, is replaced by more specific information. (The Perl
421 and Python filters, if used, may reject articles with other reasons.)
422 If the fourth field is the letter "?", the article contains strange
424 strings, such as CR without LF or LF without CR. (These characters
425 should never occur in isolation, only together as CRLF to indicate the
426 end of a line.) This log message is just informational, to give an
427 idea of how widespread such articles are; innd does not reject such
428 articles.
429 Note that when wanttrash is set to true in inn.conf and an article is
431 received that isn't posted to any valid newsgroups, it will be accepted
432 and logged with two lines, a "j" line and a minus sign line, unless the
433 logtrash parameter is set to false (in which case only the "j" line is
434 written).
435 innd also makes extensive reports through syslog(3). The first word of
437 the log message will be the name of the site if the entry is site-
438 specific (such as a "connected" message). The first word will be
439 "SERVER" if the message relates to the server itself, such as when a
440 read error occurs.
441 If the second word is the four letters "cant", then an error is being
443 reported. (The absence of an apostrophe is intentional; it makes it
444 easier to grep from the command line and easier to find error messages
445 in FAQs using a search engine. However, "can't" is also used at a few
446 places.) In this case, the next two words generally name the system
447 call or library routine that failed and the object upon which the
448 action was being performed. The rest of the line may contain other
449 information.
450 In other cases, the second word attempts to summarize what change has
452 been made, while the rest of the line gives more specific information.
453 The word "internal" generally indicates an internal logic error.
454
456 innd will catch SIGTERM and SIGHUP and shut down. If -d is used,
457 SIGINT will also be caught and will result in an orderly shutdown.
458 innd will catch the SIGUSR1 signal and recreate the control channel
460 used by ctlinnd(8).
461
463 innd normally attempts to strip IP options from incoming connections,
464 since it uses IP-based authentication and source routing can confuse
465 that. However, this doesn't work on all systems, and it doesn't work
466 at all in the presence of IPv6 support (and is disabled in that case).
467 Hence, if using innd with IPv6 support, make sure that your kernel or
468 router disables source routing.
469
471 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
472
474 active(5), ctlinnd(8), history(5), incoming.conf(5), inn.conf(5),
475 innbind(8), innfeed(8), innstat(8), libinn_dbz(3), libinn_inndcomm(3),
476 newsfeeds(5), nnrpd(8), rnews(1), syslog(3).
477INN 2.7.1 2023-03-22 INND(8)