1INND(8)                   InterNetNews Documentation                   INND(8)
2
3
4

NAME

6       innd - InterNetNews daemon
7

SYNOPSIS

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

DESCRIPTION

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
21       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
27       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
37       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
46       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
54       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

OPTIONS

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
65       -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
72           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
77           This option has no effect when systemd socket activation is used.
78
79       -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
86           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
91           This option has no effect when systemd socket activation is used.
92
93       -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
100       -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
106           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
111           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
118       -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
127       -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
139           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
142           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
146           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
149       -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
155       -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
161       -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
168       -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
172       -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
180       -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
188           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
193       -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
198       -r  Instructs innd to renumber the active file after starting, just as
199           if a "ctlinnd renumber" command were sent.
200
201       -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
205       -S  Report errors found in incoming.conf via syslog(3) and exit
206           normally.  (Yes, this is less useful than it should be.)
207
208       -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
213       -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

CONTROL MESSAGES

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
222       (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
229       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
238       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
250       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
270           *,@news.*
271           news.*
272           news.*,!control,!control.*
273           control,control.*
274
275       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
279           *,@news.*,!control,!control.*
280           comp.*,@news.*
281
282       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
292       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

PROTOCOL DIFFERENCES

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
307       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
313       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
319       3.  innd allows a wider syntax for wildmats.
320
321       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

HEADER MODIFICATIONS

327       innd modifies as few article headers as possible, although it could be
328       better in this area.
329
330       Empty header field bodies and header field bodies that consist of
331       nothing but whitespace are dropped.
332
333       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
341       The Xref header field is removed and a new one created.
342
343       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

CANCEL FEEDS

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
353       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

LOGGING

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
367           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
373       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
376       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
381       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
391       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
396       If the fourth field is a minus sign, then the article was rejected.
397       The reasons for rejection generated by innd include:
398
399           "%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
420       where %s, above, is replaced by more specific information.  (The Perl
421       and Python filters, if used, may reject articles with other reasons.)
422
423       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
430       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
436       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
442       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
451       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

SIGNALS

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
459       innd will catch the SIGUSR1 signal and recreate the control channel
460       used by ctlinnd(8).
461

BUGS

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

HISTORY

471       Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
472

SEE ALSO

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).
477
478
479
480INN 2.7.1                         2023-03-22                           INND(8)
Impressum