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

NAME

6       innd - InterNetNews daemon
7

SYNOPSIS

9       innd [-aCdfNrsSu] [-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       -C  This flag tells innd to accept and propagate but not actually
112           process cancel or supersedes messages.  This is intended for sites
113           concerned about abuse of cancels, or that wish to use another
114           cancel mechanism with stronger authentication.
115
116       -d, -f
117           innd normally puts itself into the background, points its standard
118           output and error to log files, and disassociates itself from the
119           terminal.  Using -d prevents all of this, resulting in log messages
120           being written to standard output; this is generally useful only for
121           debugging.  Using -f prevents the backgrounding and disassociation
122           but still redirects output; it may be useful if you want to monitor
123           innd with a program that would be confused by forks.
124
125       -H count, -T count, -X seconds
126           These flags control the number of connections per seconds seconds
127           that are allowed.  This code is meant to protect your server from
128           newsreader clients that make too many connections per minute (and
129           therefore these flags are probably only useful when innd is
130           spawning nnrpd).  You probably should not use these options unless
131           you're having problems.  The table used for this check is fixed at
132           128 entries and is used as a ring; the size was chosen to make
133           calculating the index easy and to be fairly sure that it won't run
134           out of space.  In practice, it is unlikely that even half the table
135           will be used at any given moment.
136
137           The -H flag limits the number of times a host is allowed to connect
138           to the server per the time interval given by -X.  The default is 2.
139
140           The -T flag limits the total number of incoming connections per the
141           time interval given by -X.  The maximum value is 128, and the
142           default is 60.
143
144           Note that the time interval given by -X is set to 0 by default,
145           that is to say no control is done on the number of connections.
146
147       -i count
148           innd normally allows a maximum number of concurrent NNTP
149           connections given by the value of maxconnections in inn.conf.  This
150           option, if given, overrides the value of that setting.  If count is
151           0, this check is suppressed.
152
153       -l size
154           innd normally rejects any article larger than the value of
155           maxartsize in inn.conf.  This option, if given, overrides the value
156           of that setting and specifies a maximum article size of size.  If
157           size is 0, this check is suppressed.
158
159       -m mode
160           Normally, innd starts in the "running" mode.  If this option is
161           given, it specifies what mode innd should start in.  mode should
162           begin with one of "g", "p", or "t", and the starting mode will be
163           set to "running", "paused", or "throttled", respectively, based on
164           that initial letter.  ("g" is short for "go".)
165
166       -N  If this option is given, any filters (Perl or Python) are disabled
167           before innd starts (normally, filters default to being enabled).
168           The filters can be enabled after innd has started with ctlinnd(8).
169
170       -n flag
171           Whether innd allows (and hands off to nnrpd) reader connections
172           while paused or throttled is normally determined by the value of
173           readerswhenstopped in inn.conf.  This option, if given, overrides
174           that value.  If flag is "n", innd will not allow readers if it is
175           paused or throttled.  If flag is "y", readers will be allowed
176           regardless of innd's operating mode.
177
178       -o count
179           This flag limits the number of file descriptors that are available
180           for outgoing file feeds.  The default is the number of available
181           file descriptors minus some reserved for internal use (which could
182           potentially starve innd of descriptors to use for accepting new
183           connections).  If innd has more file feeds than count, some of them
184           will be buffered and only written out periodically.
185
186           Normally you never need to use this option, since the number of
187           outgoing feeds is fixed, being the number of file feeds configured
188           in newsfeeds, and is generally small (particularly given that
189           innfeed(8) is now used for most outgoing feeds at large sites).
190
191       -P port
192           The port innd should listen on is normally given by the value of
193           port in inn.conf.  This option, if given, overrides that value and
194           specifies the port that innd should bind to.
195
196       -r  Instructs innd to renumber the active file after starting, just as
197           if a "ctlinnd renumber" command were sent.
198
199       -s  Just check the syntax of the newsfeeds file and exit.  innd will
200           exit with a non-zero status if any errors are found; the actual
201           errors will be reported via syslog(3).
202
203       -S  Report errors found in incoming.conf via syslog(3) and exit
204           normally.  (Yes, this is less useful than it should be.)
205
206       -t seconds
207           Normally, innd will flush any changes to history and the active
208           file after 300 seconds of inactivity.  This option changes that
209           timeout to seconds.
210
211       -u  The news log (the trace information for every article accepted by
212           innd) is normally buffered.  This option changes the log to be
213           unbuffered.
214

CONTROL MESSAGES

216       Arriving articles that have a Control: header are called "control
217       messages".  Except for cancel messages, these messages are handled by
218       controlchan(8) via a feed set up in newsfeeds.
219
220       (Cancel messages update the history database, so they must be handled
221       internally; the cost of syncing, locking, then unlocking would be too
222       high given the number of cancel messages that are received.  Note that
223       if an article is cancelled before it is received by the news server, it
224       will be rejected when it arrives since the history database has been
225       updated; it is useful for rejecting spam before it arrives.)
226
227       The distribution of control messages is different than that of standard
228       articles.  Control messages are normally filed into the pseudo-
229       newsgroup named "control" regardless of which newsgroup they were
230       actually posted to.  If, however, a "control."command newsgroup exists
231       that matches the control command, the control message will be filed
232       into that group instead.  For example, a newgroup control message will
233       be filed in "control.newgroup" if that group exists; otherwise, it will
234       be filed in "control".
235
236       If you want to specifically feed all control messages to a given site
237       regardless of whether the control messages would affect the newsgroups
238       you're feeding that site, you can put the appropriate control newsgroup
239       in the subscription list.  For example, to feed all cancel messages to
240       a given remote site (normally a bad idea), add "control.cancel" to its
241       subscription list.  Normally it's best to exclude the control
242       newsgroups from feeds to keep from sending your peers more control
243       messages than they care about.  That's why the newsfeeds pattern
244       "!control,!control.*"  is as often as not specified (adding this
245       pattern do not prevent control messages which affect the newsgroups fed
246       to a site from being sent to it).
247
248       checkgroups, newgroup and rmgroup control messages receive additional
249       special treatment.  If one of these control messages is approved and
250       posted to the newsgroup being created or removed (or to the admin group
251       to which the checkgroups is posted), the message will be sent to all
252       sites whose subscription patterns would cause them to receive articles
253       posted to that group.  For example, if a newgroup control message for a
254       nonexistent newsgroup "news.admin.meow" is received, it will be sent to
255       any site whose subscription pattern would cause it to receive
256       "news.admin.meow" if that newsgroup existed (such as a pattern of
257       "news.admin.*").  For this reason, it is correct to post newgroup
258       messages to the newsgroup that the control message would create.  It is
259       not generally correct to crosspost newgroup messages to some "well-
260       propagated" newsgroup; not only will this not actually improve their
261       propagation to sites that want such control messages, but it will also
262       cause sites that do not want those control messages to receive them.
263       Therefore, assuming that a newgroup control message is sent to the
264       group "news.admin.meow" (specified in the Newsgroups: header) in order
265       to create the group "news.admin.meow", the sites with the following
266       subscription patterns will receive it:
267
268           *,@news.*
269           news.*
270           news.*,!control,!control.*
271           control,control.*
272
273       As a matter of fact, for the first pattern, "control.newgroup" (or
274       "control") is included in "*".  However, the sites with the following
275       subscription patterns will not receive it:
276
277           *,@news.*,!control,!control.*
278           comp.*,@news.*
279
280       If a control message is posted to a group whose name ends with the four
281       characters ".ctl", this suffix is stripped off and the control message
282       is propagated as if it were posted to the base group.  For example, a
283       cancel message posted to "news.admin.ctl" will be sent to all sites
284       that subscribe to "control.cancel" (or "control" if that newsgroup
285       doesn't exist) or "news.admin".  This behavior is present for
286       historical compatibility reasons and should be considered obsolete;
287       support for the ".ctl" suffix may be removed in a future version of
288       INN.
289
290       Finally, articles posted to newsgroups beginning with "to." are treated
291       specially.  Provided that either that newsgroup exists in the active
292       file or mergetogroups is set in inn.conf, the remainder of the
293       newsgroup is taken to be a site name, as configured in newsfeeds, and
294       the article is sent to that site.  If mergetogroups is set, the article
295       will be filed in the group named "to" (which must exist in the active
296       file).  For example, with mergetogroups set, an article posted to
297       "to.uunet" will be filed in "to" and sent to the site "uunet".
298

PROTOCOL DIFFERENCES

300       innd implements the NNTP commands defined in RFC 3977 (NNTP), RFC 4643
301       (NNTP authentication), RFC 4644 (streaming NNTP feeds) and RFC 6048
302       (NNTP LIST additions) with the following differences:
303
304       1.  A batch transfer command, XBATCH byte-count, is provided.  This
305           command will read byte-count bytes and store them for later
306           processing by rnews(1) (which must be run separately, probably from
307           cron).  See innxbatch(8) and sendxbatches for more details on this
308           extension.
309
310       2.  As INN is a mode-switching news server, innd implements a limited
311           subset of the protocol useful for transferring news.  The remaining
312           commands are mostly only useful for readers and are implemented by
313           nnrpd(8).  Use of the MODE READER command will cause innd to pass
314           the connection to nnrpd.
315
316       3.  innd allows a wider syntax for wildmats.
317
318       4.  Three commands (IHAVE, CHECK and TAKETHIS) will continue, for
319           interoperability reasons, to return a reject code (respectively
320           435, 438 and 439) when the command contains a syntax error (which
321           normally leads to 501).
322

HEADER MODIFICATIONS

324       innd modifies as few article headers as possible, although it could be
325       better in this area.
326
327       Empty headers and headers that consist of nothing but whitespace are
328       dropped.
329
330       The local site's name (as set with the pathhost parameter in inn.conf)
331       and an exclamation point are prepended to the Path: header, provided
332       the first site name in the Path: header is different from the local
333       one.  In addition, pathalias and pathcluster may be similarly
334       respectively prepended and appended to the Path: header; see
335       inn.conf(5) for the details.
336
337       The Xref: header is removed and a new one created.
338
339       innd does not rewrite incorrect headers.  For example, it will not
340       replace an incorrect Lines: header, though it may reject such an
341       article depending on the value of linecountfuzz in inn.conf.
342

CANCEL FEEDS

344       In order to efficiently apply a large number of local cancels (such as
345       from processing NoCeMs or from some other external source), INN
346       supports a special feed mode available only to connections to the local
347       Unix-domain socket (not to connections to any network sockets).
348
349       To enter this mode, connect to the Unix-domain socket (pathrun/nntpin)
350       and send the command MODE CANCEL.  The response will have code 284.
351       Every subsequent line sent on that connection should consist of a
352       single message-ID.  An attempt will be made to cancel that message-ID,
353       and the server will reply 289 for success or 484 for failure.  (Failure
354       can occur, for example, if the server is paused or throttled, or the
355       message-ID is corrupt.  Failure does not occur if the article to be
356       cancelled does not exist.)
357

LOGGING

359       innd reports all incoming articles in its log file (pathlog/news).
360       This is a text file with a variable number of space-separated fields in
361       one of the following formats:
362
363           mon dd hh:mm:ss.mmm + feed <message-id> site ...
364           mon dd hh:mm:ss.mmm j feed <message-id> site ...
365           mon dd hh:mm:ss.mmm c feed <message-id> Cancelling <message-id>
366           mon dd hh:mm:ss.mmm - feed <message-id> reason
367           mon dd hh:mm:ss.mmm ? feed <message-id> reason
368
369       There may also be hostname and/or size fields after the message-ID
370       depending on the settings of nntplinklog and logartsize in inn.conf.
371
372       The first three fields are the date and time to millisecond resolution.
373       The fifth field is the site that sent the article (based on the Path:
374       header) and the sixth field is the article's message-ID; they will be a
375       question mark if the information is not available.
376
377       The fourth field indicates whether the article was accepted or not.  If
378       it is a plus sign, then the article was accepted.  If it is the letter
379       "j", then the article was accepted, providing all of the newsgroups to
380       which the article was posted were set to status "j" in the active file
381       (or not listed in the active file and wanttrash was set in inn.conf),
382       and then the article was filed into the "junk" newsgroup.  In both of
383       these cases, the article has been accepted and the "site ..." field
384       contains the space-separated list of sites to which the article is
385       being sent.
386
387       If the fourth field is the letter "c", then a cancel message was
388       accepted before the original article arrived, and a history entry for
389       the cancelled message was created so that innd will reject that message
390       if it arrives later.
391
392       If the fourth field is a minus sign, then the article was rejected.
393       The reasons for rejection generated by innd include:
394
395           "%s" header too long
396           Article exceeds local limit of %s bytes
397           Article posted in the future -- "%s"
398           Bad "%s" header
399           Can't write history
400           Duplicate
401           Duplicate "%s" header
402           EOF in headers
403           Linecount %s != %s +- %s
404           Missing %s header
405           No body
406           No colon-space in "%s" header
407           No matching newsgroups in cancel <%s>
408           No space
409           Space before colon in "%s" header
410           Too old -- "%s"
411           Unapproved for "%s"
412           Unwanted newsgroup "%s"
413           Unwanted distribution "%s"
414           Whitespace in "Newsgroups" header -- "%s"
415
416       where %s, above, is replaced by more specific information.  (The Perl
417       and Python filters, if used, may reject articles with other reasons.)
418
419       If the fourth field is the letter "?", the article contains strange
420       strings, such as CR without LF or LF without CR.  (These characters
421       should never occur in isolation, only together as CRLF to indicate the
422       end of a line.)  This log message is just informational, to give an
423       idea of how widespread such articles are; innd does not reject such
424       articles.
425
426       Note that when wanttrash is set to true in inn.conf and an article is
427       received that isn't posted to any valid newsgroups, it will be accepted
428       and logged with two lines, a "j" line and a minus sign line, unless the
429       logtrash parameter is set to false (in which case only the "j" line is
430       written).
431
432       innd also makes extensive reports through syslog(3).  The first word of
433       the log message will be the name of the site if the entry is site-
434       specific (such as a "connected" message).  The first word will be
435       "SERVER" if the message relates to the server itself, such as when a
436       read error occurs.
437
438       If the second word is the four letters "cant", then an error is being
439       reported.  (The absence of an apostrophe is intentional; it makes it
440       easier to grep from the command line and easier to find error messages
441       in FAQs using a search engine.  However, "can't" is also used at a few
442       places.)  In this case, the next two words generally name the system
443       call or library routine that failed and the object upon which the
444       action was being performed.  The rest of the line may contain other
445       information.
446
447       In other cases, the second word attempts to summarize what change has
448       been made, while the rest of the line gives more specific information.
449       The word "internal" generally indicates an internal logic error.
450

SIGNALS

452       innd will catch SIGTERM and SIGHUP and shut down.  If -d is used,
453       SIGINT will also be caught and will result in an orderly shutdown.
454
455       innd will catch the SIGUSR1 signal and recreate the control channel
456       used by ctlinnd(8).
457

BUGS

459       innd normally attempts to strip IP options from incoming connections,
460       since it uses IP-based authentication and source routing can confuse
461       that.  However, this doesn't work on all systems, and it doesn't work
462       at all in the presence of IPv6 support (and is disabled in that case).
463       Hence, if using innd with IPv6 support, make sure that your kernel or
464       router disables source routing.
465

HISTORY

467       Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
468

SEE ALSO

470       active(5), ctlinnd(8), history(5), incoming.conf(5), inn.conf(5),
471       innbind(8), innfeed(8), innstat(8), libinn_dbz(3), libinn_inndcomm(3),
472       newsfeeds(5), nnrpd(8), rnews(1), syslog(3).
473
474
475
476INN 2.6.5                         2022-02-18                           INND(8)
Impressum