INND(8)

💅 INND — the InterNetNews daemon 💅

welcome to innd(8) bestie, grab a snack, this one's a journey 🍓

✨ NAME ✨

innd — the InterNetNews daemon, aka the main character of your news server 👑

---

🌸 SYNOPSIS 🌸

innd [-adfNrsSu] [-4 address] [-6 address] [-c days] [-H count] [-i
count] [-l size] [-m mode] [-n flag] [-o count] [-P port] [-t timeout]
[-T count] [-X seconds]

---

🦋 DESCRIPTION 🦋

okay so picture this: innd is the InterNetNews daemon, and it is literally the one handling all your incoming NNTP feeds. It coordinates the storage, retransmission, and overview generation for every single accepted article, and it manages the active(5) and history(5) databases. Like, it does everything. 💅

It handles incoming connections on the NNTP port, and it also creates and listens to a local Unix-domain stream socket so it can receive articles from local processes such as nnrpd(8) and rnews(1). networking, but make it cozy 🫶

As the master daemon, innd should generally be started at boot and just, like, always be running. It listens to a Unix-domain datagram socket for commands that control its activities — commands you can send with ctlinnd(8). Wanna know the current status of innd? Run "ctlinnd mode", or if you want the detailed tea, innstat(8). 🔥

So innd can be in one of three operating modes, and yes this is on the quiz:

• running — the normal mode, everything's chill ✨
• throttled — the server closes connections and rejects new ones 😭
• paused — like a temporary throttle, it suspends innd's activities but does not cause the server to shut down existing connections

The mode is normally changed via ctlinnd(8) — either by various automated processes (such as nightly article expiration) or manually by the news administrator. But plot twist: innd will also throttle itself if it encounters ENOSPC errors when writing data, or an excessive number of I/O errors (among other problems). self-care era 💀

innd normally takes care of spawning nnrpd(8) to handle connections from news reading clients, but it can be run on a separate port from nnrpd(8) so that feed connections and news reading connections are handled separately (this can often be faster, no cap). Normally innd listens on port 119, the assigned port for NNTP. If it's desirable to run innd and nnrpd(8) on separate ports, it's recommended that nnrpd(8) be given port 119 (since many news reading clients connect only to that port) and that port 433 be used for innd. okay that's the port lore 🎀

The primary configuration files that control innd's activities are:

• incoming.conf — specifies what remote sites innd will accept connections from
• newsfeeds — specifies what is to be done with incoming articles besides storing them
• inn.conf — sets a wide variety of configuration parameters

Some parameters in inn.conf(5) can also be set with command-line flags. For these, the command-line flags take precedence if used. periodt.

innd must be run as the news user and news group. It will check for this at startup and fail to start if it's not run properly — like, it will notice. 🙈 Normally it should be started via rc.news(8) as part of the system boot up process. It relies on the setuid root helper program innbind(8) to listen on a privileged port (119, 433 or 563). slay.

---

💜 OPTIONS 💜

For the options below that override inn.conf settings, see inn.conf(5) for the default values if neither the inn.conf setting nor the command-line option is given. iykyk ✨

• -4 address — Normally, innd binds to all local IP addresses (unless bindaddress is set in inn.conf). If this option is given, it specifies the IP address that INN should bind as. This is only relevant for servers with multiple local IP addresses. The IP address must be in dotted-quad ("nnn.nnn.nnn.nnn") format.

If this option is specified, it's the same as setting bindaddress in inn.conf and may cause changes in whether INN binds to an IPv6 address as well. See inn.conf(5) for more details and also the -6 flag for innd.

This option has no effect when systemd socket activation is used. 💀

• -6 address — Only applies when INN has been built with IPv6 support. Normally innd binds to all local IP addresses (unless bindaddress6 is set in inn.conf). If this option is given, it specifies the IPv6 address that INN should bind to. The IPv6 address must be in colon-separated RFC 4291 format ("n:n:n:n:n:n:n:n").

If this option is specified, it's the same as setting bindaddress6 in inn.conf and may cause changes in whether INN binds to an IPv4 address as well. See inn.conf(5) for more details and also the -4 flag for innd.

This option has no effect when systemd socket activation is used. 💀

• -a — By default, if a host connects to innd but is not listed in incoming.conf, the connection is handed off to nnrpd (or rejected if noreader is set in inn.conf). If -a is given, incoming.conf is ignored and any host can connect and transfer articles. This flag should never be used with an accessible server connected to Usenet — it would open the server up for all sorts of abuse. do NOT do this bestie, i'm serious 😭
• -c days — innd normally rejects any article that is older (in days) than the value of artcutoff in inn.conf. This option, if given, overrides the value of that setting. If days is 0, this check is suppressed and innd will accept articles regardless of how old they are.

Note that rejected articles are remembered during the number of days specified by the "/remember/" line in expire.ctl(5). You'll have to wait that number of days before being able to inject again an article with the same previously rejected Message-ID.

In case you need re-injecting articles before that amount of time, you'll have to set "/remember/" to "0" in expire.ctl, run the expire process (for instance via news.daily called with the same parameters as in crontab, plus "notdaily") and undo the change in expire.ctl. All previously rejected or removed articles will then not be considered as duplicate if their Message-ID is proposed. ✨ loophole unlocked ✨

• -d, -f — innd normally puts itself into the background, points its standard output and error to log files, and disassociates itself from the terminal. Using -d prevents all of this, resulting in log messages being written to standard output; this is generally useful only for debugging. Using -f prevents the backgrounding and disassociation but still redirects output; it may be useful if you want to monitor innd with a program that would be confused by forks. 🍴
• -H count, -T count, -X seconds — These flags control the number of connections per seconds seconds that are allowed. This code is meant to protect your server from newsreader clients that make too many connections per minute (and therefore these flags are probably only useful when innd is spawning nnrpd). You probably should not use these options unless you're having problems. The table used for this check is fixed at 128 entries and is used as a ring; the size was chosen to make calculating the index easy and to be fairly sure that it won't run out of space. In practice, it is unlikely that even half the table will be used at any given moment. 🎀
  • The -H flag limits the number of times a host is allowed to connect to the server per the time interval given by -X. The default is "2".
  • The -T flag limits the total number of incoming connections per the time interval given by -X. The maximum value is "128", and the default is "60".

Note that the time interval given by -X is set to "0" by default, that is to say no control is done on the number of connections. so it's lowkey off unless you turn it on 🌈

• -i count — innd normally allows a maximum number of concurrent NNTP connections given by the value of maxconnections in inn.conf. This option, if given, overrides the value of that setting. If count is "0", this check is suppressed.
• -l size — innd normally rejects any article larger than the value of maxartsize in inn.conf. This option, if given, overrides the value of that setting and specifies a maximum article size of size. If size is "0", this check is suppressed.
• -m mode — Normally, innd starts in the "running" mode. If this option is given, it specifies what mode innd should start in. mode should begin with one of "g", "p", or "t", and the starting mode will be set to "running", "paused", or "throttled", respectively, based on that initial letter. ("g" is short for "go".) cute 💅
• -N — If this option is given, any filters (Perl or Python) are disabled before innd starts (normally, filters default to being enabled). The filters can be enabled after innd has started with ctlinnd(8). 🔥
• -n flag — Whether innd allows (and hands off to nnrpd) reader connections while paused or throttled is normally determined by the value of readerswhenstopped in inn.conf. This option, if given, overrides that value. If flag is "n", innd will not allow readers if it is paused or throttled. If flag is "y", readers will be allowed regardless of innd's operating mode. yes/no energy 🫶
• -o count — This flag limits the number of file descriptors that are available for outgoing file feeds. The default is the number of available file descriptors minus some reserved for internal use (which could potentially starve innd of descriptors to use for accepting new connections). If innd has more file feeds than count, some of them will be buffered and only written out periodically.

Normally you never need to use this option, since the number of outgoing feeds is fixed, being the number of file feeds configured in newsfeeds, and is generally small (particularly given that innfeed(8) is now used for most outgoing feeds at large sites). so like, don't touch it unless you must 🎀

• -P port — The port innd should listen on is normally given by the value of port in inn.conf. This option, if given, overrides that value and specifies the port that innd should bind to.
• -r — Instructs innd to renumber the active file after starting, just as if a "ctlinnd renumber" command were sent. 🌀
• -s — Just check the syntax of the newsfeeds file and exit. innd will exit with a non-zero status if any errors are found; the actual errors will be reported via syslog(3). vibe check only, no launching 🌸
• -S — Report errors found in incoming.conf via syslog(3) and exit normally. (Yes, this is less useful than it should be.) 💀
• -t seconds — Normally, innd will flush any changes to history and the active file after 300 seconds of inactivity. This option changes that timeout to seconds.
• -u — The news log (the trace information for every article accepted by innd) is normally buffered. This option changes the log to be unbuffered. ✨

🎛️ CONTROL MESSAGES 🎛️

Okay bestie, so articles that show up with a Control header field? Those are called “control messages.” Except for cancel messages, they get handled by controlchan(8) through a feed set up in newsfeeds. Slay, but with routing rules.

(Cancel messages are the exception because they update the history database, so they have to be handled internally. The cost of syncing, locking, then unlocking would be way too high given how many cancel messages get received. Also note: if an article is cancelled before it’s received by the news server, it will be rejected when it arrives since the history database has already been updated — which is genuinely useful for rejecting spam before it arrives. Iconic.)

The distribution of control messages is different from standard articles. Control messages are normally filed into the pseudo-newsgroup named control regardless of which newsgroup they were actually posted to. But if a control.command newsgroup exists that matches the control command, the control message gets filed into that group instead. Example: a newgroup control message will be filed in control.newgroup if that group exists; otherwise, it goes into control.

If you want to specifically feed all control messages to a given site regardless of whether those control messages would affect the newsgroups you’re feeding that site, you can put the appropriate control newsgroup in the subscription list. For example, to feed all cancel messages to a given remote site (normally a bad idea), add control.cancel to its subscription list. Normally it’s best to exclude the control newsgroups from feeds to keep from sending your peers more control messages than they care about. That’s why the newsfeeds pattern !control,!control.* is as often as not specified — adding this pattern does not prevent control messages which affect the newsgroups fed to a site from being sent to it.

checkgroups, newgroup and rmgroup control messages receive additional special treatment. If one of these control messages is approved and posted to the newsgroup being created or removed (or to the admin group to which the checkgroups is posted), the message will be sent to all sites whose subscription patterns would cause them to receive articles posted to that group. For example, if a newgroup control message for a nonexistent newsgroup news.admin.meow is received, it will be sent to any site whose subscription pattern would cause it to receive news.admin.meow if that newsgroup existed (such as a pattern of news.admin.*).

For this reason, it is correct to post newgroup messages to the newsgroup that the control message would create. It is not generally correct to crosspost newgroup messages to some well-propagated newsgroup; not only will this not actually improve their propagation to sites that want such control messages, but it will also cause sites that do not want those control messages to receive them. Therefore, assuming that a newgroup control message is sent to the group news.admin.meow (specified in the Newsgroups header field body) in order to create the group news.admin.meow, the sites with the following subscription patterns will receive it:

    *,@news.*
    news.*
    news.*,!control,!control.*
    control,control.*

As a matter of fact, for the first pattern, control.newgroup (or control) is included in *. However, the sites with the following subscription patterns will not receive it:

    *,@news.*,!control,!control.*
    comp.*,@news.*

If a control message is posted to a group whose name ends with the four characters .ctl, this suffix is stripped off and the control message is propagated as if it were posted to the base group. For example, a cancel message posted to news.admin.ctl will be sent to all sites that subscribe to control.cancel (or control if that newsgroup doesn’t exist) or news.admin. This behavior is present for historical compatibility reasons and should be considered obsolete; support for the .ctl suffix may be removed in a future version of INN.

Finally, articles posted to newsgroups beginning with to. are treated specially. Provided that either that newsgroup exists in the active file or mergetogroups is set in inn.conf, the remainder of the newsgroup is taken to be a site name, as configured in newsfeeds, and the article is sent to sites propagating to.uunet. If mergetogroups is set, the article will be filed in the group named to (which must exist in the active file). For example, with mergetogroups set, an article posted to to.uunet will be filed in to and sent to the sites propagating to.uunet.

---

🛰️ PROTOCOL DIFFERENCES 🛰️

innd implements the NNTP commands defined in RFC 3977 (NNTP), RFC 4643 (NNTP authentication), RFC 4644 (streaming NNTP feeds) and RFC 6048 (NNTP LIST additions) with the following differences:

1. A batch transfer command, XBATCH byte-count, is provided. This command will read byte-count bytes and store them for later processing by rnews(1) (which must be run separately, probably from cron). See innxbatch(8) and sendxbatches for more details on this extension.
2. As INN is a mode-switching news server, innd implements a limited subset of the protocol useful for transferring news. The remaining commands are mostly only useful for readers and are implemented by nnrpd(8). Use of the MODE READER command will cause innd to pass the connection to nnrpd.
3. innd allows a wider syntax for wildmats.
4. Three commands (IHAVE, CHECK and TAKETHIS) will continue, for interoperability reasons, to return a reject code (respectively 435, 438 and 439) when the command contains a syntax error (which normally leads to 501).

---

💇 HEADER MODIFICATIONS 💇

innd modifies as few article headers as possible, although it could be better in this area. We respect the low-effort king energy.

Empty header field bodies and header field bodies that consist of nothing but whitespace are dropped.

The local site’s name (as set with the pathhost parameter in inn.conf) and an exclamation point are prepended to the Path header field body, provided the first site name in the Path header field body is different from the local one. In addition, pathalias and pathcluster may be similarly respectively prepended and appended as path identities immediately to the right or the left of pathhost in the Path header field body; see inn.conf(5) for the details.

The Xref header field is removed and a new one created.

innd does not rewrite incorrect header fields. For example, it will not replace an incorrect Lines header field, though it may reject such an article depending on the value of linecountfuzz in inn.conf.

---

🚫 CANCEL FEEDS 🚫

In order to efficiently apply a large number of local cancels (such as from processing NoCeMs or from some other external source), INN supports a special feed mode available only to connections to the local Unix-domain socket — not to connections to any network sockets. Very “local bestie only,” no long-distance calls.

To enter this mode, connect to the Unix-domain socket (pathrun/nntpin) and send the command MODE CANCEL. The response will have code 284. Every subsequent line sent on that connection should consist of a single message-ID. An attempt will be made to cancel that message-ID, and the server will reply 289 for success or 484 for failure. (Failure can occur, for example, if the server is paused or throttled, or the message-ID is corrupt. Failure does not occur if the article to be cancelled does not exist.)

🌸 LOGGING 🌸

okay so innd is literally journaling its whole life into pathlog/news — that's a text file, bestie, and it's giving variable-number-of-space-separated-fields realness. The lines come in one of these formats:

mon dd hh:mm:ss.mmm + feed <message-id> site ...
mon dd hh:mm:ss.mmm j feed <message-id> site ...
mon dd hh:mm:ss.mmm c feed <message-id> Cancelling <message-id>
mon dd hh:mm:ss.mmm - feed <message-id> reason
mon dd hh:mm:ss.mmm ? feed <message-id> reason

Depending on how nntplinklog and logartsize are set in inn.conf, there may also be hostname and/or size fields after the message-ID. slay.

The first three fields are the date and time, down to millisecond resolution. Field five is the site that sent the article — based on the Path header field body — and field six is the article's Message-ID. Both of those will just be a question mark if the info isn't available. no cap.

Field four is the vibe check on whether the article was accepted:

• A plus sign means accepted. 💖
• The letter j means the article was accepted — provided all the newsgroups it was posted to were set to status j in the active file (or not listed in the active file and wanttrash was set in inn.conf) — and then it got filed into the junk newsgroup.

In both of those cases the article has been accepted, and the site ... field holds the space-separated list of sites the article is being sent to. periodt.

If field four is the letter c, then a cancel message was accepted before the original article even arrived, and a history entry for the cancelled message was created so that innd will reject that message if it shows up later. iconic, honestly.

If field four is a minus sign, the article was rejected 😭 and the reasons generated by innd include:

"%s" header too long
Article exceeds local limit of %s bytes
Article posted in the future -- "%s"
Bad "%s" header field
Can't write history
Duplicate
Duplicate "%s" header field
EOF in headers
Linecount %s != %s +- %s
Missing %s header field
No body
No colon-space in "%s" header field
No matching newsgroups in cancel <%s>
No space
Space before colon in "%s" header field
Too old -- "%s"
Unapproved for "%s"
Unwanted newsgroup "%s"
Unwanted distribution "%s"
Whitespace in "Newsgroups" header field -- "%s"

where "%s" (up above) gets replaced with more specific info. (And the Perl and Python filters, if you're using them, may reject articles with other reasons too.)

If field four is the letter ?, the article contains strange strings — like CR without LF, or LF without CR. (These characters should never occur in isolation, only together as CRLF to indicate the end of a line.) This log message is purely informational, just to give an idea of how widespread such articles are; innd does not reject articles like this. 🙈

Note that when wanttrash is set to true in inn.conf and an article is received that isn't posted to any valid newsgroups, it will be accepted and logged with two lines — a j line and a minus sign line — unless the logtrash parameter is set to false (in which case only the j line gets written).

innd also makes extensive reports through syslog(3). The first word of the log message is the name of the site if the entry is site-specific (like a connected message). The first word will be SERVER if the message relates to the server itself, like when a read error occurs. 👑

If the second word is the four letters cant, then an error is being reported. (The missing apostrophe is intentional — it makes it easier to grep from the command line and easier to find error messages in FAQs using a search engine. Though can't is also used in a few places. iykyk.) In this case, the next two words generally name the system call or library routine that failed and the object upon which the action was being performed. The rest of the line may contain other information.

In other cases, the second word tries to summarize what change has been made, while the rest of the line gives the more specific details. The word internal generally indicates an internal logic error. 💀

---

✨ SIGNALS ✨

innd will catch SIGTERM and SIGHUP and shut down. If -d is used, SIGINT will also be caught and will result in an orderly shutdown. 🫶

innd will also catch the SIGUSR1 signal and recreate the control channel used by ctlinnd(8). slay.

---

🎀 HISTORY 🎀

Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. we stan a legend.

---

🌈 SEE ALSO 🌈

active(5), ctlinnd(8), history(5), incoming.conf(5), inn.conf(5), innbind(8), innfeed(8), innstat(8), libinn_dbz(3), libinn_inndcomm(3), newsfeeds(5), nnrpd(8), rnews(1), syslog(3).

---

and that's the whole page, bestie — this was INN 2.7.4, dated 2025-03-29, and the manpage literally calls itself INND(8). go off, icon. 💅✨