=head1 NAME innd - InterNetNews daemon =head1 SYNOPSIS B [B<-aCdfNrsu>] [B<-c> I] [B<-H> I] [B<-i> I] [B<-I> I
] [B<-l> I] [B<-m> I] [B<-n> I] [B<-o> I] [B<-p> I] [B<-P> I] [B<-t> I] [B<-T> I] [B<-X> I] =head1 DESCRIPTION B, the InterNetNews daemon, handles all incoming NNTP feeds, coordinates the storage, retransmission, and overview generation for all accepted articles, and manages the active(5) and history(5) databases. It handles incoming connections on the NNTP port, and also creates and listens to a local Unix-domain stream socket in order to receive articles from local processes such as nnrpd(8) and rnews(1). As the master daemon, B should generally be started at boot and be always running. It listens to a Unix-domain datagram socket for commands to control its activites, commands that can be sent using ctlinnd(8). The current status of B can be obtained by running C, or for more detailed output, innstat(8). B can be in one of three operating modes: running, paused, or throttled. Running is the normal mode; when the server is throttled, it closes connections and rejects new ones. Paused is like a temporary throttle, suspending B's activities but not causing 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 B will also throttle itself if it encounters ENOSPC errors in writing data or an excessive number of I/O errors (among other problems). B 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). Normally, B listens on port 119, the assigned port for NNTP; if it is desireable to run B 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 B. The primary configuration files that control B's activities are F, which specifies what remote sites B will accept connections from, F, which specifies what is to be done with incoming articles besides storing them, and F, which 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. B should normally not run directly. It must run as the news user or all sorts of file ownership problems may result, and normally the port it listens on (119 or 433) is privileged and must be opened by root. Instead, B should normally be started via inndstart(8), a small setuid-root program that opens the appropriate port, cleans up the environment, changes to the news user, and then runs B, passing along any command-line arguments. To use IPv6, B must be started by B. =head1 OPTIONS For the options below that override F settings, see inn.conf(5) for the default values if neither the F setting nor the command-line option is given. =over 4 =item B<-a> By default, if a host connects to B but is not listed in F, the connection is handed off to B (or rejected if I is set in F). If B<-a> is given, F 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. =item B<-c> I B normally rejects any article that is older (in days) than the value of I in F. This option, if given, overrides the value of that setting. If I is 0, this check is suppressed and B will accept articles regardless of how old they are. =item B<-C> This flag tells B to accept and propagate but not actually process cancel or supersede messages. This is intended for sites concerned about abuse of cancels, or that wish to use another cancel mechanism with stronger authentication. =item B<-d>, B<-f> B normally puts itself into the background, points its standard output and error to log files, and disassociates itself from the terminal. Using B<-d> prevents all of this, resulting in log messages being written to standard output; this is generally useful only for debugging. Using B<-f> prevents the backgrounding and disassociation but still redirects output; it may be useful if you want to monitor B with a program that would be confused by forks. =item B<-H> I, B<-T> I, B<-X> I These flags control the number of connections per minute 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 B is spawning B). 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 B<-H> flag limits the number of times a host is allowed to connect to the server per the time interval given by B<-X>. The default is C<2>. The B<-T> flag limits the total number of incoming connections per the time interval given by B<-X>. The maximum value is C<128>, and the default is C<60>. =item B<-i> I B normally allows a maximum number of concurrent NNTP connections given by the value of I in F. This option, if given, overrides the value of that setting. If I is C<0>, this check is suppressed. =item B<-I> I
Normally if B itself binds to a port, it lets the operating system pick the source IP address (unless I is set in F). 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 (C) format. This option is rarely useful since B should not be binding to a port itself. Instead, use inndstart(8) and its analgous B<-I> option. =item B<-l> I B normally rejects any article larger than the value of I in F. This option, if given, overrides the value of that setting and specifies a maximum article size of I. If I is C<0>, this check is suppressed. =item B<-m> I Normally B starts in the C mode. If this option is given, it specifies what mode B should start in. I should begin with one of C, C

, or C, and the starting mode will be set to C, C, or C, respectively, based on that initial letter. (C is short for C.) =item B<-N> If this option is given, any filters (Perl, Tcl, or Python) are disabled before B starts (normally, filters default to being enabled). The filters can be enabled after B has started with ctlinnd(8). =item B<-n> I Whether B allows (and hands off to B) reader connections while paused or throttled is normally determined by the value of I in F). This option, if given, overrides that value. If I is C, B will not allow readers if it is paused or throttled. If I is C, readers will be allowed regardless of B's operating mode. =item B<-o> I 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 B of descriptors to use for accepting new connections). If B has more file feeds than I, 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 F, and is generally small (particularly given that innfeed(8) is now used for most outgoing feeds at large sites). =item B<-p> I If this flag is given, B expects the file descriptor given by I to already be open and bound to the appropriate local port and to be suitable for listening to for incoming connections. This is how B tells B which open file descriptor is the network connection. If this flag is not given, B will attempt to open its network socket itself. B always passes this flag to B. =item B<-P> I The port B should listen on is normally given by the value of I in F. This option, if given, overrides that value and specifies the port that B should bind to. This option is rarely useful since B normally does not bind itself; instead the analgous B<-P> option to inndstart(8) should be used. Since B should never be run as root, I has to be a non-privileged port (one larger than 1024). =item B<-r> Instructs B to renumber the F file after starting, just as if a C command were sent. =item B<-s> Just check the syntax of the F file and exit. B will exit with a non-zero status if any errors are found; the actual errors will be reported via syslog(3). =item B<-t> I Normally, B will flush any changes to history and the active file after 300 seconds of inactivity. This option changes that timeout to I. =item B<-u> The news log (the trace information for every article accepted by B) is normally buffered. This option changes the log to be unbuffered. =back =head1 CONTROL MESSAGES Arriving articles that have a Control: header are called "control messages". Except for cancel messages, these messages are handled by controlchan(8) via a feed set up in F. (Cancel messages update the history database, so they must be handled internally; the cost of syncing, locking, then unlocking would be too high given the number of cancel messages that are received. Note that if an article is cancelled before it is received by the news server, it will be rejected when it arrives since the history database has been updated; it is useful for rejecting spam before it arrives.) The distribution of control messages is different than that of standard articles. Control messages are normally filed into the pseudo-newsgroup named C regardless of which newsgroup they were actually posted to. If, however, a CI newsgroup exists that matches the control command, the control message will be filed into that group instead. For example, a newgroup control message will be filed in C if that group exists; otherwise, it will be filed in C. If you want to specifically feed all control messages to a given site regardless of whether the 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 C 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 F pattern C is as often as not specified (adding this pattern do 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 C is received, it will be sent to any site whose subscription pattern would cause it to receive C if that newsgroup existed (such as a pattern of C). For this reason, it is correct to post newgroup messages to the newsgroup that the control message would create. It is I 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 C (specified in the Newsgroups: header) in order to create the group C, the sites with the following subscription patterns will receive it: *,@news.* news.* news.*,!control,!control.* control,control.* but 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 C<.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 C will be sent to all sites that subscribe to C (or C if that newsgroup doesn't exist) or C. This behavior is present for historical compatibility reasons and should be considered obsolete; support for the C<.ctl> suffix may be removed in a future version of INN. Finally, articles posted to newsgroups beginning with C are treated specially. Provided that either that newsgroup exists in the F file or I is set in F, the remainder of the newsgroup is taken to be a site name, as configured in F, and the article is sent to that site. If I is set, the article will be filed in the group named C (which must exist in the F file). For example, with I set, an article posted to C will be filed in C and sent to the site C. =head1 PROTOCOL DIFFERENCES B implements the NNTP commands defined in RFC 977, with the following differences: =over 4 =item 1. The LIST command may be followed by an optional ACTIVE, ACTIVE.TIMES, or NEWSGROUPS. There is only basic support for LIST in B since feeding peers normally don't need it; see nnrpd(8) for full support. =item 2. The AUTHINFO USER and AUTHINFO PASS commands are implemented, although the authentication is currently limited to matching a password for a given peer specified in F. These are based on the reference Unix implementation. =item 3. A new command, MODE READER, is implemented. This command will cause the server to pass the connection to B. =item 4. The streaming extension (MODE STREAM, CHECK, and TAKETHIS) is fully supported. =item 5. A batch transfer command, XBATCH I, is provided. This command will read I bytes and store them for later processing by rnews(1) (which must be run separately, probably from cron). See innxbatch(8) and F for more details on this extension. =item 6. B implements a limited subset of the protocol useful for transferring news. The only other commands implemented are HEAD, HELP, IHAVE, STAT, and QUIT. The remaining commands are mostly only useful for readers and are implemented by nnrpd(8). =back =head1 HEADER MODIFICATIONS B modifies as few article headers as possible, although it could be better in this area. Empty headers and headers that consist of nothing but whitespace are dropped. The local site's name (as set with the I parameter in F) and an exclamation point are prepended to the Path: header, provided the first site name in the Path: header is different from the local one. In addition, I and I may be similarly respectively prepended and appended to the Path: header; see inn.conf(5) for the details. The Xref: header is removed and a new one created. A Lines: header will be added if the article was missing one. B does not rewrite incorrect headers. For example, it will not replace an incorrect Lines header, though it may reject such an article depending on the value of I in F. =head1 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). To enter this mode, connect to the Unix domain socket (I/nntpin) and send the command MODE CANCEL. The response will have code C<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 C<289> for success or C<484> for failure. (Failure can occur, for example, if the server is paused or throttled, or the Message-ID is corrupt. Failure does I occur if the article to be cancelled does not exist.) =head1 LOGGING B reports all incoming articles in its log file (I/news). This is a text file with a variable number of space-separated fields in one of the following formats: mon dd hh:mm:ss.mmm + feed site ... mon dd hh:mm:ss.mmm j feed site ... mon dd hh:mm:ss.mmm c feed Cancelling mon dd hh:mm:ss.mmm - feed reason mon dd hh:mm:ss.mmm ? feed reason There may also be hostname and/or size fields after the message ID depending on the settings of I and I in F. The first three fields are the date and time to millisecond resolution. The fifth field is the site that sent the article (based on the Path header) and the sixth field is the article's message ID; they will be a question mark if the information is not available. The fourth field indicates whether the article was accepted or not. If it is a plus sign, then the article was accepted. If it is the letter C then the article was accepted, but all of the newsgroups to which the article was posted were set to mode C in the active file (or not listed in the active file and I was set in F) so the article was filed into the C newsgroup. In both of these cases, the article has been accepted and the C field contains the space-separated list of sites to which the article is being sent. If the fourth field is the letter C, then a cancel message was accepted before the original article arrived, and a history entry for the cancelled message was created so that B will reject that message if it arrives later. If the fourth field is a minus sign, then the article was rejected. The reasons for rejection generated by B include: "%s" header too long "%s" wants to cancel <%s> by "%s" Article exceeds local limit of %s bytes Article posted in the future -- "%s" Bad "%s" header Can't write history Duplicate Duplicate "%s" header EOF in headers Linecount %s != %s +- %s Missing %s header No body No colon-space in "%s" header No space Space before colon in "%s" header Too old -- "%s" Unapproved for "%s" Unwanted newsgroup "%s" Unwanted distribution "%s" Whitespace in "Newsgroups" header -- "%s" where C<%s>, above, is replaced by more specific information. (The Perl, Python, andr Tcl filters, if used, may reject articles with other reasons.) If the fourth field is the letter C, the article contains strange strings, such as 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 just informational, to give an idea of how widespread such articles are; B does not reject such articles. Note that when I is set to true in F and an article is received that isn't posted to any valid newsgroups, it will be accepted and logged with two lines, a C line and a minus sign line. B also makes extensive reports through syslog(3). The first word of the log message will be the name of the site if the entry is site-specific (such as a "connected" message). The first word will be C if the message relates to the server itself, such as when a read error occurs. If the second word is the four letters C, then an error is being reported. (The absence of an 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.) 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 attempts to summarize what change has been made, while the rest of the line gives more specific information. The word C generally indicates an internal logic error. =head1 SIGNALS B will catch SIGTERM and SIGHUP and shut down. If B<-d> is used, SIGINT will also be caught and will result in an orderly shutdown. B will catch the SIGUSR1 signal and recreate the control channel used by ctlinnd(8). =head1 BUGS B normally attempts to strip IP options from incoming connections, since it uses IP-based authentication and source routing can confuse that. However, this doesn't work on all systems, and it doesn't work at all in the presence of IPv6 support (and is disabled in that case). Hence, if using B with IPv6 support, make sure that your kernel or router disables source routing. =head1 HISTORY Written by Rich $alz for InterNetNews. $Id: innd.pod 7748 2008-04-06 13:49:56Z iulius $ =head1 SEE ALSO active(5), ctlinnd(8), dbz(3), history(5), incoming.conf(5), inn.conf(5), newsfeeds(5), nnrpd(8), rnews(1), syslog(3). =cut