1INND(8) InterNetNews Documentation INND(8)
2
6 innd - InterNetNews daemon
7
9 innd [-aCdfNrsu] [-c days] [-H count] [-i count] [-I address] [-l size]
10 [-m mode] [-n flag] [-o count] [-p fd] [-P port] [-t timeout] [-T
11 count] [-X seconds]
12
14 innd, the InterNetNews daemon, handles all incoming NNTP feeds, coordi‐
15 nates the storage, retransmission, and overview generation for all
16 accepted articles, and manages the active(5) and history(5) databases.
17 It handles incoming connections on the NNTP port, and also creates and
18 listens to a local Unix-domain stream socket in order to receive arti‐
19 cles 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 com‐
23 mands to control its activites, 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 han‐
40 dled separately (this can often be faster). Normally, innd listens on
41 port 119, the assigned port for NNTP; if it is desireable 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 con‐
48 nections 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 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
56 it listens on (119 or 433) is privileged and must be opened by root.
57 Instead, 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 innd, passing
60 along any command-line arguments.
61 To use IPv6, innd must be started by inndstart.
63
65 For the options below that override inn.conf settings, see inn.conf(5)
66 for the default values if neither the inn.conf setting nor the command-
67 line option is given.
68 -a By default, if a host connects to innd but is not listed in incom‐
70 ing.conf, the connection is handed off to nnrpd (or rejected if
71 noreader is set in inn.conf). If -a is given, incoming.conf is
72 ignored and any host can connect and transfer articles. This flag
73 should never be used with an accessible server connected to Usenet;
74 it would open the server up for all sorts of abuse.
75 -c days
77 innd normally rejects any article that is older (in days) than the
78 value of artcutoff in inn.conf. This option, if given, overrides
79 the value of that setting. If days is 0, this check is suppressed
80 and innd will accept articles regardless of how old they are.
81 -C This flag tells innd to accept and propagate but not actually
83 process cancel or supersede messages. This is intended for sites
84 concerned about abuse of cancels, or that wish to use another can‐
85 cel mechanism with stronger authentication.
86 -d, -f
88 innd normally puts itself into the background, points its standard
89 output and error to log files, and disassociates itself from the
90 terminal. Using -d prevents all of this, resulting in log messages
91 being written to standard output; this is generally useful only for
92 debugging. Using -f prevents the backgrounding and disassociation
93 but still redirects output; it may be useful if you want to monitor
94 innd with a program that would be confused by forks.
95 -H count, -T count, -X seconds
97 These flags control the number of connections per minute that are
98 allowed. This code is meant to protect your server from newsreader
99 clients that make too many connections per minute (and therefore
100 these flags are probably only useful when innd is spawning nnrpd).
101 You probably should not use these options unless you're having
102 problems. The table used for this check is fixed at 128 entries
103 and is used as a ring; the size was chosen to make calculating the
104 index easy and to be fairly sure that it won't run out of space.
105 In practice, it is unlikely that even half the table will be used
106 at any given moment.
107 The -H flag limits the number of times a host is allowed to connect
109 to the server per the time interval given by -X. The default is 2.
110 The -T flag limits the total number of incoming connections per the
112 time interval given by -X. The maximum value is 128, and the
113 default is 60.
114 -i count
116 innd normally allows a maximum number of concurrent NNTP connec‐
117 tions given by the value of maxconnections in inn.conf. This
118 option, if given, overrides the value of that setting. If count is
119 0, this check is suppressed.
120 -I address
122 Normally if innd itself binds to a port, it lets the operating sys‐
123 tem pick the source IP address (unless bindaddress is set in
124 inn.conf). If this option is given, it specifies the IP address
125 that INN should bind as. This is only relevant for servers with
126 multiple local IP addresses. The IP address must be in dotted quad
127 ("nnn.nnn.nnn.nnn") format.
128 This option is rarely useful since innd should not be binding to a
130 port itself. Instead, use inndstart(8) and its analgous -I option.
131 -l size
133 innd normally rejects any article larger than the value of maxart‐
134 size in inn.conf. This option, if given, overrides the value of
135 that setting and specifies a maximum article size of size. If size
136 is 0, this check is suppressed.
137 -m mode
139 Normally innd starts in the "running" mode. If this option is
140 given, it specifies what mode innd should start in. mode should
141 begin with one of "g", "p", or "t", and the starting mode will be
142 set to "running", "paused", or "throttled", respectively, based on
143 that initial letter. ("g" is short for "go".)
144 -N If this option is given, any filters (Perl, Tcl, or Python) are
146 disabled before innd starts (normally, filters default to being
147 enabled). The filters can be enabled after innd has started with
148 ctlinnd(8).
149 -n flag
151 Whether innd allows (and hands off to nnrpd) reader connections
152 while paused or throttled is normally determined by the value of
153 readerswhenstopped in inn.conf). This option, if given, overrides
154 that value. If flag is "n", innd will not allow readers if it is
155 paused or throttled. If flag is "y", readers will be allowed
156 regardless of innd's operating mode.
157 -o count
159 This flag limits the number of file descriptors that are available
160 for outgoing file feeds. The default is the number of available
161 file descriptors minus some reserved for internal use (which could
162 potentially starve innd of descriptors to use for accepting new
163 connections). If innd has more file feeds than count, some of them
164 will be buffered and only written out periodically.
165 Normally you never need to use this option, since the number of
167 outgoing feeds is fixed, being the number of file feeds configured
168 in newsfeeds, and is generally small (particularly given that inn‐
169 feed(8) is now used for most outgoing feeds at large sites).
170 -p fd
172 If this flag is given, innd expects the file descriptor given by fd
173 to already be open and bound to the appropriate local port and to
174 be suitable for listening to for incoming connections. This is how
175 inndstart tells innd which open file descriptor is the network con‐
176 nection. If this flag is not given, innd will attempt to open its
177 network socket itself. inndstart always passes this flag to innd.
178 -P port
180 The port innd should listen on is normally given by the value of
181 port in inn.conf. This option, if given, overrides that value and
182 specifies the port that innd should bind to. This option is rarely
183 useful since innd normally does not bind itself; instead the anal‐
184 gous -P option to inndstart(8) should be used. Since innd should
185 never be run as root, port has to be a non-privileged port (one
186 larger than 1024).
187 -r Instructs innd to renumber the active file after starting, just as
189 if a "ctlinnd renumber" command were sent.
190 -s Just check the syntax of the newsfeeds file and exit. innd will
192 exit with a non-zero status if any errors are found; the actual
193 errors will be reported via syslog(3).
194 -t seconds
196 Normally, innd will flush any changes to history and the active
197 file after 300 seconds of inactivity. This option changes that
198 timeout to seconds.
199 -u The news log (the trace information for every article accepted by
201 innd) is normally buffered. This option changes the log to be
202 unbuffered.
203
205 Arriving articles that have a Control header are called "control mes‐
206 sages". Except for cancel messages, these messages are handled by con‐
207 trolchan(8) via a feed set up in newsfeeds.
208 (Cancel messages update the history database, so they must be handled
210 internally; the cost of syncing, locking, then unlocking would be too
211 high given the number of cancel messages that are received.)
212 The distribution of control messages is different than that of standard
214 articles. Control messages are normally filed into the pseudo-news‐
215 group named "control" regardless of which newsgroup they were actually
216 posted to. If, however, a "control."command newsgroup exists that
217 matches the control command, the control message will be filed into
218 that group instead. For example, a newgroup control message will be
219 filed in "control.newgroup" if that group exists; otherwise, it will be
220 filed in "control".
221 If you want to specifically feed all control messages to a given site
223 regardless of whether the control messages would affect the newsgroups
224 you're feeding that site, you can put the appropriate control newsgroup
225 in the subscription list. For example, to feed all cancel messages to
226 a given remote site (normally a bad idea), add "control.cancel" to its
227 subscription list. Normally it's best to exclude the control news‐
228 groups from feeds to keep from sending your peers more control messages
229 than they care about.
230 newgroup and rmgroup control messages receive additional special treat‐
232 ment. If one of these control messages is approved and posted to the
233 newsgroup being created or removed, the message will be sent to all
234 sites whose subscription patterns would cause them to receive articles
235 posted to that group. For example, if a newgroup control message for a
236 nonexistent newsgroup "news.admin.meow" is received, it will be sent to
237 any site whose subscription pattern would cause it to receive
238 "news.admin.meow" if that newsgroup existed (such as a pattern of
239 "news.admin.*"). For this reason, it is correct to post newgroup mes‐
240 sages to the newsgroup that the control message would create. It is
241 not generally correct to crosspost newgroup messages to some
242 "well-propagated" newsgroup; not only will this not actually improve
243 their propagation to sites that want such control messages, but it will
244 also cause sites that do not want those control messages to receive
245 them.
246 If a control message is posted to a group whose name ends with the four
248 characters ".ctl", this suffix is stripped off and the control message
249 is propagated as if it were posted to the base group. For example, a
250 cancel message posted to "news.admin.ctl" will be sent to all sites
251 that subscribe to "control.cancel" (or "control" if that newsgroup
252 doesn't exist) or "news.admin". This behavior is present for histori‐
253 cal compatibility reasons and should be considered obsolete; support
254 for the ".ctl" suffix may be removed in a future version of INN.
255 Finally, articles posted to newsgroups beginning with "to." are treated
257 specially. Provided that either that newsgroup exists in the active
258 file or mergetogroups is set in inn.conf, the remainder of the news‐
259 group is taken to be a site name, as configured in newsfeeds, and the
260 article is sent to that site. If mergetogroups is set, the article
261 will be filed in the group named "to" (which must exist in the active
262 file). For example, with mergetogroups set, an article posted to
263 "to.uunet" will be filed in "to" and sent to the site "uunet".
264
266 innd implements the NNTP commands defined in RFC 977, with the follow‐
267 ing differences:
268 1. The LIST command may be followed by an optional ACTIVE,
270 ACTIVE.TIMES, or NEWSGROUPS. There is only basic support for LIST
271 in innd since feeding peers normally don't need it; see nnrpd(8)
272 for full support.
273 2. The AUTHINFO USER and AUTHINFO PASS commands are implemented,
275 although the authentication is currently limited to matching a
276 password for a given peer specified in incoming.conf. These are
277 based on the reference Unix implementation.
278 3. A new command, MODE READER, is implemented. This command will
280 cause the server to pass the connection to nnrpd.
281 4. The streaming extension (MODE STREAM, CHECK, and TAKETHIS) is fully
283 supported.
284 5. A batch transfer command, XBATCH byte-count, is provided. This
286 command will read byte-count bytes and store them for later pro‐
287 cessing by rnews(1) (which must be run separately, probably from
288 cron). See innxbatch(8) and backends/sendxbatches for more details
289 on this extension.
290 6. innd implements a limited subset of the protocol useful for trans‐
292 ferring news. The only other commands implemented are HEAD, HELP,
293 IHAVE, STAT, and QUIT. The remaining commands are mostly only use‐
294 ful for readers and are implemented by nnrpd(8).
295
297 innd modifies as few article headers as possible, although it could be
298 better in this area.
299 Empty headers and headers that consist of nothing but whitespace are
301 dropped.
302 The local site's name (as set with the pathhost parameter in inn.conf)
304 and an exclamation point are prepended to the Path: header, provided
305 the first site name in the Path: header is different from the local
306 one. In addition, pathalias may be similarly prepended to the Path:
307 header; see inn.conf(5) for the details.
308 The Xref: header is removed and a new one created.
310 A Lines: header will be added if the article was missing one.
312 innd does not rewrite incorrect headers. For example, it will not
314 replace an incorrect Lines header, though it may reject such an article
315 depending on the value of linecountfuzz in inn.conf.
316
318 In order to efficiently apply a large number of local cancels (such as
319 from processing NoCeMs or from some other external source), INN sup‐
320 ports a special feed mode available only to connections to the local
321 Unix domain socket (not to connections to any network sockets).
322 To enter this mode, connect to the Unix domain socket (pathrun/nntpin)
324 and send the command MODE CANCEL. The response will have code 284.
325 Every subsequent line sent on that connection should consist of a sin‐
326 gle message ID. An attempt will be made to cancel that message ID, and
327 the server will reply 289 for success or 484 for failure. (Failure can
328 occur, for example, if the server is paused or throttled, or the Mes‐
329 sage-ID is corrupt. Failure does not occur if the article to be can‐
330 celled does not exist.)
331
333 innd reports all incoming articles in its log file (pathlog/news).
334 This is a text file with a variable number of space-separated fields in
335 one of the following formats:
336 mon dd hh:mm:ss.mmm + feed <message-id> site ...
338 mon dd hh:mm:ss.mmm j feed <message-id> site ...
339 mon dd hh:mm:ss.mmm c feed <message-id> Cancelling <message-id>
340 mon dd hh:mm:ss.mmm - feed <message-id> reason
341 mon dd hh:mm:ss.mmm ? feed <message-id> reason
342 There may also be hostname and/or size fields after the message ID
344 depending on the settings of nntplinklog and logartsize in inn.conf.
345 The first three fields are the date and time to millisecond resolution.
347 The fifth field is the site that sent the article (based on the Path
348 header) and the sixth field is the article's message ID; they will be a
349 question mark if the information is not available.
350 The fourth field indicates whether the article was accepted or not. If
352 it is a plus sign, then the article was accepted. If it is the letter
353 "j" then the article was accepted, but all of the newsgroups to which
354 the article was posted were set to mode "j" in the active file (or not
355 listed in the active file and wanttrash was set in inn.conf) so the
356 article was filed into the "junk" newsgroup. In both of these cases,
357 the article has been accepted and the "site ..." field contains the
358 space-separated list of sites to which the article is being sent.
359 If the fourth field is the letter "c", then a cancel message was
361 accepted before the original article arrived, and a history entry for
362 the cancelled message was created so that innd will reject that message
363 if it arrives later.
364 If the fourth field is a minus sign, then the article was rejected.
366 The reasons for rejection generated by innd include:
367 "%s" header too long
369 "%s" wants to cancel <%s> by "%s"
370 Article exceeds local limit of %s bytes
371 Article posted in the future -- "%s"
372 Bad "%s" header
373 Can't write history
374 Duplicate
375 Duplicate "%s" header
376 EOF in headers
377 Linecount %s != %s +- %s
378 Missing %s header
379 No body
380 No colon-space in "%s" header
381 No space
382 Space before colon in "%s" header
383 Too old -- "%s"
384 Unapproved for "%s"
385 Unwanted newsgroup "%s"
386 Unwanted distribution "%s"
387 Whitespace in "Newsgroups" header -- "%s"
388 where %s, above, is replaced by more specific information. (The Perl,
390 Python, andr Tcl filters, if used, may reject articles with other rea‐
391 sons.)
392 If the fourth field is the letter "?", the article contains strange
394 strings, such as CR without LF or LF without CR. (These characters
395 should never occur in isolation, only together as CRLF to indicate the
396 end of a line.) This log message is just informational, to give an
397 idea of how widespread such articles are; innd does not reject such
398 articles.
399 Note that when wanttrash is set to true in inn.conf and an article is
401 received that isn't posted to any valid newsgroups, it will be accepted
402 and logged with two lines, a "j" line and a minus sign line.
403 innd also makes extensive reports through syslog(3). The first word of
405 the log message will be the name of the site if the entry is site-spe‐
406 cific (such as a "connected" message). The first word will be "SERVER"
407 if the message relates to the server itself, such as when a read error
408 occurs.
409 If the second word is the four letters "cant", then an error is being
411 reported. (The absence of an apostrophe is intentional; it makes it
412 easier to grep from the command line and easier to find error messages
413 in FAQs using a search engine.) In this case, the next two words gen‐
414 erally name the system call or library routine that failed and the
415 object upon which the action was being performed. The rest of the line
416 may contain other information.
417 In other cases, the second word attempts to summarize what change has
419 been made, while the rest of the line gives more specific information.
420 The word "internal" generally indicates an internal logic error.
421
423 innd will catch SIGTERM and SIGHUP and shut down. If -d is used, SIG‐
424 INT will also be caught and will result in an orderly shutdown.
425 innd will catch the SIGUSR1 signal and recreate the control channel
427 used by ctlinnd(8).
428
430 innd normally attempts to strip IP options from incoming connections,
431 since it uses IP-based authentication and source routing can confuse
432 that. However, this doesn't work on all systems, and it doesn't work
433 at all in the presence of IPv6 support (and is disabled in that case).
434 Hence, if using innd with IPv6 support, make sure that your kernel or
435 router disables source routing.
436
438 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
439 $Id: innd.8 6265 2003-03-19 00:19:59Z vinocur $
441
443 active(5), ctlinnd(8), dbz(3), history(5), incoming.conf(5),
444 inn.conf(5), newsfeeds(5), nnrpd(8), rnews(1), syslog(3).
445INN 2.4.0 2003-03-18 INND(8)