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

[INN Commit]

    Date: Wednesday, September 2, 2015 @ 05:35:17
  Author: iulius
Revision: 9936

Improve documentation about the use of port 119 with TLS

Modified:
  trunk/doc/pod/checklist.pod
  trunk/doc/pod/install.pod
  trunk/doc/pod/nnrpd.pod

---------------+
 checklist.pod |    6 ++++--
 install.pod   |    6 ++++--
 nnrpd.pod     |   19 ++++++++++++-------
 3 files changed, 20 insertions(+), 11 deletions(-)

Modified: checklist.pod
===================================================================
--- checklist.pod	2015-09-02 12:23:29 UTC (rev 9935)
+++ checklist.pod	2015-09-02 12:35:17 UTC (rev 9936)
@@ -334,8 +334,10 @@
     su news -s /bin/sh -c '<pathbin>/nnrpd -D -c <pathetc>/readers-ssl.conf -p 563 -S'
 
 Note that a news client which supports the STARTTLS command can also
-use the conventional NNTP port 119 to initiate a TLS connection.  However,
-such clients are not widespread yet.
+use the conventional NNTP port 119 to initiate a TLS connection.
+However, as such clients are not widespread yet, using the separate
+port 563 is still common practice (though discouraged).  See nnrpd(8)
+for more information about TLS support.
 
 =back
 

Modified: install.pod
===================================================================
--- install.pod	2015-09-02 12:23:29 UTC (rev 9935)
+++ install.pod	2015-09-02 12:35:17 UTC (rev 9936)
@@ -1614,8 +1614,10 @@
 connection is allowed to read and post news (you can also use the
 previously created F<readers.conf> file to handle TLS/SSL connections).
 Note that a news client which supports the STARTTLS command can also
-use the conventional NNTP port 119 to initiate a TLS connection.  However,
-such clients are not widespread yet.
+use the conventional NNTP port 119 to initiate a TLS connection.
+However, as such clients are not widespread yet, using the separate
+port 563 is still common practice (though discouraged).  See nnrpd(8)
+for more information about TLS support.
 
 In the shutdown section of the init script, you can put:
 

Modified: nnrpd.pod
===================================================================
--- nnrpd.pod	2015-09-02 12:23:29 UTC (rev 9935)
+++ nnrpd.pod	2015-09-02 12:35:17 UTC (rev 9936)
@@ -207,13 +207,18 @@
 In case you have a certificate authority root certificate, you can also
 set I<tlscafile> to its path.
 
-Most news clients currently do not use the STARTTLS command, however, and
-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 along with C<-p 563> and put into your init scripts:
+There are two common ways for a news client to negotiate a TLS
+connection:  either via the use of the STARTTLS command on the usual NNTP
+port (119) or via the now discouraged way (per RFC 4642) to immediately
+negotiate an encrypted session upon connection on a dedicated port
+(usually 563).  As most news clients currently do not use the STARTTLS
+command, and instead expect to connect to a separate port (563) and start
+a TLS negotiation immediately, it is still useful to provide a legacy
+way for these news clients to encrypt the NNTP session.  B<innd> does
+not, however, know how to listen for connections to that separate port.
+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 along
+with C<-p 563> and put into your init scripts:
 
     su news -s /bin/sh -c '<pathbin>/nnrpd -D -p 563 -S'