INN commit: trunk/doc/pod (nnrpd.pod)

[INN Commit]

    Date: Monday, May 18, 2009 @ 12:59:31
  Author: iulius
Revision: 8478

Update the documentation of nnrpd, especially the part about
RFC 977 and additions to the protocol (which are now in
RFC 3977, 4642 and 4643).

Modified:
  trunk/doc/pod/nnrpd.pod

-----------+
 nnrpd.pod |  133 +++++++++++++++++++++++-------------------------------------
 1 file changed, 53 insertions(+), 80 deletions(-)

Modified: nnrpd.pod
===================================================================
--- nnrpd.pod	2009-05-18 17:27:48 UTC (rev 8477)
+++ nnrpd.pod	2009-05-18 19:59:31 UTC (rev 8478)
@@ -15,7 +15,7 @@
 invoked by innd(8) with those descriptors attached to a remote client
 connection.  B<nnrpd> also supports running as a standalone daemon.
 
-Unlike innd(8) B<nnrpd> supports all NNTP commands for user-oriented
+Unlike innd(8), B<nnrpd> supports all NNTP commands for user-oriented
 reading and posting.  B<nnrpd> uses the F<readers.conf> file to control
 who is authorized to access the Usenet database.
 
@@ -36,10 +36,10 @@
 options should not be used with I<nnrpdflags>.  See also the discussion
 of I<nnrpdflags> in inn.conf(5).
 
-When I<nnrpdloadlimit> in F<inn.conf> is not 0, it will also reject
-connections if the load average is greater than that value (typically 16).
-B<nnrpd> can also prevent high-volume posters from abusing your
-resources. See the discussion of exponential backoff in inn.conf(5).
+When I<nnrpdloadlimit> in F<inn.conf> is not C<0>, it will also reject
+connections if the load average is greater than that value (typically
+C<16>).  B<nnrpd> can also prevent high-volume posters from abusing
+your resources.  See the discussion of exponential backoff in inn.conf(5).
 
 =head1 OPTIONS
 
@@ -74,7 +74,7 @@
 By default, B<nnrpd> reads the F<readers.conf> to determine how to
 authenticate connections.  The B<-c> flag specifies an alternate file
 for this purpose.  If the file name isn't fully qualified, it is taken
-to be relative to I<pathetc> in F<inn.conf> (this is useful to have
+to be relative to I<pathetc> in F<inn.conf>.  (This is useful to have
 several instances of B<nnrpd> running on different ports or IP
 addresses with different settings.)
 
@@ -82,12 +82,12 @@
 
 If specified, this parameter causes B<nnrpd> to operate as a daemon.  That
 is, it detaches itself and runs in the background, forking a process for
-every connection.  By default B<nnrpd> listens on the NNTP port (119), so
-either innd(8) has to be started on another port or B<nnrpd> B<-p>
-parameter.  Note that with this parameter, B<nnrpd> continues running
+every connection.  By default, B<nnrpd> listens on the NNTP port (119), so
+either innd(8) has to be started on another port or the B<-p> parameter
+used.  Note that with this parameter, B<nnrpd> continues running
 until killed.  This means that it reads F<inn.conf> once on startup and
 never again until restarted.  B<nnrpd> should therefore be restarted if
-inn.conf is changed.
+F<inn.conf> is changed.
 
 When started in daemon mode, B<nnrpd> will write its PID into a file in
 the I<pathrun> directory.  The file will be named F<nnrpd-%d.pid>, where
@@ -106,8 +106,8 @@
 
 =item B<-I> I<instance>
 
-If specified I<instance> is used as an additional static portion
-within MessageIDs generated by B<nnrpd>; typically this option would
+If specified, I<instance> is used as an additional static portion
+within message-IDs generated by B<nnrpd>; typically this option would
 be used where a cluster of machines exist with the same virtual
 hostname and must be disambiguated during posts.
 
@@ -121,9 +121,9 @@
 =item B<-o>
 
 The B<-o> flag causes all articles to be spooled instead of sending
-them to innd(8). B<rnews> with the B<-U> flag should be invoked from
-cron on a regular basis to take care of these articles. This flag is
-useful if innd(8) in accepting articles and B<nnrpd> is started
+them to innd(8).  B<rnews> with the B<-U> flag should be invoked from
+cron on a regular basis to take care of these articles.  This flag is
+useful if innd(8) is accepting articles and B<nnrpd> is started
 standalone or using inetd(8).
 
 =item B<-p> I<port>
@@ -140,34 +140,34 @@
 =item B<-r> I<reason>
 
 If the B<-r> flag is used, then B<nnrpd> will reject the incoming
-connection giving I<reason> as the text. This flag is used by innd(8)
+connection giving I<reason> as the text.  This flag is used by innd(8)
 when it is paused or throttled.
 
 =item B<-s> I<padding>
 
 As each command is received, B<nnrpd> tries to change its C<argv>
-array so that ps(1) will print out the command being executed. To get
+array so that ps(1) will print out the command being executed.  To get
 a full display, the B<-s> flag may be used with a long string as its
 argument, which will be overwritten when the program changes its
 title.
 
 =item B<-S>
 
-If specified, B<nnrpd> will start a negotiation for SSL session as
-soon as connected. To use this flag, B<--with-openssl> must have been
+If specified, B<nnrpd> will start a negotiation for a TLS session as
+soon as connected.  To use this flag, B<--with-openssl> must have been
 specified at configure time.  For more information on running B<nnrpd>
-with SSL support, see L<SSL SUPPORT>.
+with TLS support, see L<TLS SUPPORT>.
 
 =item B<-t>
 
-If the B<-t> flag is used then all client commands and initial
-responses will be traced by reporting them in syslog. This flag is set
+If the B<-t> flag is used, then all client commands and initial
+responses will be traced by reporting them in syslog.  This flag is set
 by innd(8) under the control of the ctlinnd(8) C<trace> command, and
-is toggled upon receipt of a C<SIGHUP>; see signal(2).
+is toggled upon receipt of a SIGHUP; see signal(2).
 
 =back
 
-=head1 SSL SUPPORT
+=head1 TLS SUPPORT
 
 If INN is built with B<--with-openssl>, B<nnrpd> will support news reading
 over TLS (also known as SSL).  For clients that use the STARTTLS command,
@@ -194,12 +194,12 @@
 name the certificate is for.
 
 Most news clients currently do not use the STARTTLS command, however, and
-instead expect to connect to a separate port (563) and start an SSL
+instead expect to connect to a separate port (563) and start a TLS
 negotiation immediately.  B<innd> does not, however, know how to listen
 for connections to that port and then spawn B<nnrpd> the way that it does
 for regular reader connections.  You will therefore need to arrange for
 B<nnrpd> to listen on that port through some other means.  This can be
-done with the B<-D> flag (and C<-p 563>) and put into your init scripts:
+done with the B<-D> flag along with C<-p 563> and put into your init scripts:
 
     su news -c '<pathbin>/nnrpd -D -p 563 -S'
 
@@ -214,80 +214,53 @@
 
 =head1 PROTOCOL DIFFERENCES
 
-B<nnrpd> implements the NNTP commands defined in S<RFC 977>, with the
+B<nnrpd> implements the NNTP commands defined in S<RFC 3977> (NNTP),
+S<RFC 4642> (TLS/NNTP) and S<RFC 4643> (NNTP authentication) with the
 following differences:
 
 =over 4
 
 =item 1.
 
-The C<slave> command is not implemented.  This command has never been
-fully defined.
+Besides the keywords defined in S<RFC 3977> (ACTIVE, ACTIVE.TIMES,
+DISTRIB.PATS, HEADERS, NEWSGROUPS and OVERVIEW.FMT), the LIST command
+may be followed by the optional keywords DISTRIBUTIONS, MODERATORS, MOTD
+and SUBSCRIPTIONS to get a list of valid distributions, the moderators list,
+the message of the day information for readers, or a list of the
+automatic group subscriptions.
 
 =item 2.
 
-The C<list> command may be followed by the optional word C<active.times>,
-C<distrib.pats>, C<distributions>, C<moderators>, C<motd>, C<newsgroups>,
-C<overview.fmt>, or C<subscriptions> to get a list of when newsgroups
-where created, a file specifying default distribution patterns, a list
-of valid distributions, the moderators list, the message of the day information
-for readers, a one-per-line description of the current set of newsgroups,
-a listing of the overview fields for which the overview database is consistent
-(see I<extraoverviewadvertised> in F<inn.conf> for more information), or
-a list of the automatic group subscriptions.
+The XGTITLE [I<wildmat>] command is provided.  This extension is used by
+ANU-News and documented in S<RFC 2980>.  It returns a C<282> reply code,
+followed by a one-line description of all newsgroups that match the
+pattern.  The default is the current group.
 
-The command C<list active> is equivalent to the C<list> command. This
-is a common extension.
+Note that LIST NEWSGROUPS should be used instead of XGTITLE.
 
 =item 3.
 
-The C<xhdr>, C<authinfo user> and C<authinfo pass> commands are
-implemented.  These are based on the reference Unix implementation.  See
-S<RFC 2980>.
+The XHDR I<header> [I<message-ID>|I<range>] command is implemented.  It is
+based on the reference Unix implementation.  See S<RFC 2980>.
 
 =item 4.
 
-A new command, C<xpat header range|MessageID pat [morepat...]>, is
-provided.  The first argument is the case-insensitive name of the header
-to be searched.  The second argument is either an article range or a
-single Message-ID, as specified in S<RFC 977>.  The third argument is a
-C<uwildmat>(3)-style pattern; if there are additional arguments they are
-joined together separated by a single space to form the complete pattern.
-This command is similar to the C<xhdr> command.  It returns a C<221>
-response code, followed by the text response of all article numbers that
-match the pattern.
-
-=item 5.
-
-The C<listgroup group> command is provided.  This is a comment extension.
-It is equivalent to the C<group> command, except that the reply is a
-multi-line response containing the list of all article numbers in the
-group.
-
-=item 6.
-
-The C<xgtitle [group]> command is provided. This extension is used by
-ANU-News.  It returns a C<282> reply code, followed by a one-line
-description of all newsgroups thatmatch the pattern.  The default is the
-current group.
-
-=item 7.
-
-The C<xover [range]> command is provided. It returns a C<224> reply code,
+The XOVER [I<range>] command is provided. It returns a C<224> reply code,
 followed by the overview data for the specified range; the default is to
 return the data for the current article.
 
-=item 8.
+=item 5.
 
-The C<xpath MessageID> command is provided; see innd(8).
+A new command, XPAT I<header> I<message-ID>|I<range> I<pattern>
+[I<pattern> ...], is provided.  The first argument is the case-insensitive
+name of the header to be searched.  The second argument is either an article
+range or a single message-ID, as specified in S<RFC 2980>.  The third
+argument is a uwildmat(3)-style pattern; if there are additional arguments,
+they are joined together separated by a single space to form the complete
+pattern.  This command is similar to the XHDR command.  It returns a C<221>
+response code, followed by the text response of all article numbers that
+match the pattern.
 
-=item 9.
-
-The C<date> command is provided; this is based on the draft NNTP protocol
-revision (draft-ietf-nntpext-imp-04.txt).  It returns a one-line response
-code of C<111> followed by the GMT date and time on the server in the form
-C<YYYYMMDDhhmmss>.
-
 =back
 
 =head1 HISTORY
@@ -301,6 +274,6 @@
 
 =head1 SEE ALSO
 
-ctlinnd(8), innd(8), inn.conf(5), signal(2), uwildmat(3).
+ctlinnd(8), innd(8), inn.conf(5), readers.conf(5), signal(2), uwildmat(3).
 
 =cut