INN commit: branches/2.5/doc/pod (innd.pod)
INN Commit
rra at isc.org
Sun Jan 17 13:08:06 UTC 2010
Date: Sunday, January 17, 2010 @ 05:08:06
Author: iulius
Revision: 8895
* Update protocol differences for innd, now that RFCs 3977, 4643
and 4644 have been implemented.
* Mention that the -X flag is unset by default.
* The Lines: header is not added by *innd*.
* Other typos.
Modified:
branches/2.5/doc/pod/innd.pod
----------+
innd.pod | 118 ++++++++++++++++++++++++++++---------------------------------
1 file changed, 55 insertions(+), 63 deletions(-)
Modified: innd.pod
===================================================================
--- innd.pod 2010-01-17 13:04:04 UTC (rev 8894)
+++ innd.pod 2010-01-17 13:08:06 UTC (rev 8895)
@@ -20,7 +20,7 @@
As the master daemon, B<innd> 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
+to control its activities, commands that can be sent using ctlinnd(8). The
current status of B<innd> can be obtained by running C<ctlinnd mode>, or
for more detailed output, innstat(8).
@@ -38,7 +38,7 @@
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<innd> listens on port
-119, the assigned port for NNTP; if it is desireable to run B<innd> and
+119, the assigned port for NNTP; if it is desirable to run B<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 B<innd>.
@@ -53,7 +53,7 @@
B<innd> must be run as the news user and news group. It will check for
this at startup and fail to start if not run properly. Normally it should
-be started via rc.news(8) as part of the system bootup process. It relies
+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).
@@ -67,7 +67,7 @@
=item B<-4> I<address>
-Normally B<innd> binds to all local IP addresses (unless I<bindaddress> is
+Normally, B<innd> binds to all local IP addresses (unless I<bindaddress> is
set in F<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
@@ -108,7 +108,7 @@
=item B<-C>
This flag tells B<innd> to accept and propagate but not actually process
-cancel or supersede messages. This is intended for sites concerned about
+cancel or supersedes messages. This is intended for sites concerned about
abuse of cancels, or that wish to use another cancel mechanism with
stronger authentication.
@@ -124,15 +124,15 @@
=item B<-H> I<count>, B<-T> I<count>, B<-X> I<seconds>
-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<innd> is spawning B<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.
+These flags control the number of connections per I<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 B<innd> is spawning B<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 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>.
@@ -141,6 +141,9 @@
time interval given by B<-X>. The maximum value is C<128>, and the
default is C<60>.
+Note that the time interval given by B<-X> is set to C<0> by default,
+that is to say no control is done on the number of connections.
+
=item B<-i> I<count>
B<innd> normally allows a maximum number of concurrent NNTP connections
@@ -157,7 +160,7 @@
=item B<-m> I<mode>
-Normally B<innd> starts in the C<running> mode. If this option is given,
+Normally, B<innd> starts in the C<running> mode. If this option is given,
it specifies what mode B<innd> should start in. I<mode> should begin with
one of C<g>, C<p>, or C<t>, and the starting mode will be set to
C<running>, C<paused>, or C<throttled>, respectively, based on that
@@ -173,7 +176,7 @@
Whether B<innd> allows (and hands off to B<nnrpd>) reader connections
while paused or throttled is normally determined by the value of
-I<readerswhenstopped> in F<inn.conf>). This option, if given, overrides
+I<readerswhenstopped> in F<inn.conf>. This option, if given, overrides
that value. If I<flag> is C<n>, B<innd> will not allow readers if it is
paused or throttled. If I<flag> is C<y>, readers will be allowed
regardless of B<innd>'s operating mode.
@@ -211,7 +214,7 @@
=item B<-t> I<seconds>
-Normally, B<innd> will flush any changes to history and the active file
+Normally, B<innd> will flush any changes to history and the F<active> file
after 300 seconds of inactivity. This option changes that timeout to
I<seconds>.
@@ -304,49 +307,39 @@
=head1 PROTOCOL DIFFERENCES
-B<innd> implements the NNTP commands defined in S<RFC 977>, with the
-following differences:
+B<innd> implements the NNTP commands defined in S<RFC 3977> (NNTP),
+S<RFC 4643> (NNTP authentication) and S<RFC 4644> (streaming) 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<innd> since feeding
-peers normally don't need it; see nnrpd(8) for full support.
+A batch transfer command, XBATCH I<byte-count>, is provided. This command
+will read I<byte-count> bytes and store them for later processing by
+rnews(1) (which must be run separately, probably from cron). See
+innxbatch(8) and B<sendxbatches> for more details on this
+extension.
=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<incoming.conf>. These are based on the reference Unix
-implementation.
+As INN is a mode-switching news server, B<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 B<innd> to pass the connection
+to B<nnrpd>.
=item 3.
-A new command, MODE READER, is implemented. This command will cause the
-server to pass the connection to B<nnrpd>.
+B<innd> allows a wider syntax for wildmats.
=item 4.
-The streaming extension (MODE STREAM, CHECK, and TAKETHIS) is fully
-supported.
+Three commands (IHAVE, CHECK and TAKETHIS) will continue, for
+interoperability reasons, to return a reject code (respectively C<435>,
+C<438> and C<439>) when the command contains a syntax error (which normally
+leads to C<501>).
-=item 5.
-
-A batch transfer command, XBATCH I<byte-count>, is provided. This command
-will read I<byte-count> bytes and store them for later processing by
-rnews(1) (which must be run separately, probably from cron). See
-innxbatch(8) and F<backends/sendxbatches> for more details on this
-extension.
-
-=item 6.
-
-B<innd> 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
@@ -366,26 +359,24 @@
The Xref: header is removed and a new one created.
-A Lines: header will be added if the article was missing one.
-
B<innd> does not rewrite incorrect headers. For example, it will not
-replace an incorrect Lines header, though it may reject such an article
+replace an incorrect Lines: header, though it may reject such an article
depending on the value of I<linecountfuzz> in F<inn.conf>.
=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
+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<pathrun>/nntpin)
+To enter this mode, connect to the Unix-domain socket (I<pathrun>/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
+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<not> occur if the article to be
+message-ID is corrupt. Failure does I<not> occur if the article to be
cancelled does not exist.)
=head1 LOGGING
@@ -400,20 +391,20 @@
mon dd hh:mm:ss.mmm - feed <message-id> reason
mon dd hh:mm:ss.mmm ? feed <message-id> reason
-There may also be hostname and/or size fields after the message ID
+There may also be hostname and/or size fields after the message-ID
depending on the settings of I<nntplinklog> and I<logartsize> in
F<inn.conf>.
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
+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<j>
+is a plus sign, then the article was accepted. If it is the letter C<j>,
then the article was accepted, but all of the newsgroups to which the
-article was posted were set to mode C<j> in the active file (or not listed
-in the active file and I<wanttrash> was set in F<inn.conf>) so the article
+article was posted were set to status C<j> in the F<active> file (or not listed
+in the F<active> file and I<wanttrash> was set in F<inn.conf>) so the article
was filed into the C<junk> newsgroup. In both of these cases, the article
has been accepted and the C<site ...> field contains the space-separated
list of sites to which the article is being sent.
@@ -468,10 +459,10 @@
If the second word is the four letters C<cant>, 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.
+FAQs using a search engine. However, C<can't> is also used at a few places.)
+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
@@ -503,6 +494,7 @@
=head1 SEE ALSO
active(5), ctlinnd(8), dbz(3), history(5), incoming.conf(5), inn.conf(5),
-innbind(8), newsfeeds(5), nnrpd(8), rnews(1), syslog(3).
+innbind(8), innfeed(8), innstat(8), newsfeeds(5), nnrpd(8), rnews(1),
+syslog(3).
=cut
More information about the inn-committers
mailing list