INN commit: branches/2.6 (13 files)

INN Commit rra at isc.org
Mon Sep 18 20:13:49 UTC 2017


    Date: Monday, September 18, 2017 @ 13:13:48
  Author: iulius
Revision: 10179

Clarify the use of FQDN in documentation

There are two things here. First, the FQDNs that exist in the DNS for a given host: some may be A and AAAA records, other may be CNAME records, and the host may know them or not.

Second, the FQDN that the host system will report (hostname --fqdn), which is a single one, always the same as long as the configuration will not change. With GNU/Linux, it seems to be determined this way:

* if the system hostname contains a dot, return it;
* if the system hostname does not contain a dot, resolve it to an FQDN  using getaddrinfo() (which will resolve it to an IP address and then  back to a name using a reverse resolution, usually using /etc/hosts,  but possibly using the DNS).

The problem is mostly the over-usage of the term ?\226?\128?\156FQDN?\226?\128?\157, which can sometimes be incorrectly understood as meaning ?\226?\128?\156a host's canonical name?\226?\128?\157. This is emphasized by the fact that some news services, if not most of them, are referred to with a service name such as news.example.com, which is fully qualified, but which is just an alias to the server canonical name such as gruyere.example.com, which will probably be the result of a reverse lookup of its IP address as well.

Most of the time, when resolving a host name to an IP address), the fact that it is fully qualified or not is irrelevant, as long as it does resolve. In such cases, it is enough to just mention ?\226?\128?\156a host name?\226?\128?\157.

For checking a client IP address against a host name, the fact that it is FQ or not is again irrelevant, but what is relevant is whether this check is done by direct lookup of the configured host name, or by reverse lookup of its IP address.

For reporting connections with a host name rather than an IP address, it is not relevant either, this is just a reverse lookup, and it will almost always return an FQDN indeed, but that depends on the system configuration.

Thanks to Tanguy Ortolo for his suggestion of improvement.

Modified:
  branches/2.6/CONTRIBUTORS
  branches/2.6/doc/man/libinn.3
  branches/2.6/doc/man/nnrpd.track.5
  branches/2.6/doc/pod/incoming.conf.pod
  branches/2.6/doc/pod/inn.conf.pod
  branches/2.6/doc/pod/innfeed.conf.pod
  branches/2.6/doc/pod/install.pod
  branches/2.6/doc/pod/news.pod
  branches/2.6/doc/pod/nnrpd.pod
  branches/2.6/lib/getfqdn.c
  branches/2.6/nnrpd/auth-ext.c
  branches/2.6/samples/incoming.conf
  branches/2.6/samples/nntpsend.ctl

---------------------------+
 CONTRIBUTORS              |    3 ++-
 doc/man/libinn.3          |    4 ++--
 doc/man/nnrpd.track.5     |    2 +-
 doc/pod/incoming.conf.pod |    9 +++++----
 doc/pod/inn.conf.pod      |   24 +++++++++++++-----------
 doc/pod/innfeed.conf.pod  |    8 +++++---
 doc/pod/install.pod       |   15 ++++++++-------
 doc/pod/news.pod          |    2 +-
 doc/pod/nnrpd.pod         |    7 ++++---
 lib/getfqdn.c             |    3 ++-
 nnrpd/auth-ext.c          |    2 +-
 samples/incoming.conf     |    7 ++++---
 samples/nntpsend.ctl      |    2 +-
 13 files changed, 49 insertions(+), 39 deletions(-)

Modified: CONTRIBUTORS
===================================================================
--- CONTRIBUTORS	2017-09-18 20:13:08 UTC (rev 10178)
+++ CONTRIBUTORS	2017-09-18 20:13:48 UTC (rev 10179)
@@ -277,4 +277,5 @@
 Dennis Preiser, Paolo Amoroso, Dennis Davis, River Tarnell, Jochen Schmitt,
 Tim Fardell, Remco Rijnders, David Binderman, Tony Evans, Christian Garbs,
 Jesse Rehmer, Colin Watson, Lauri Tirkkonen, Christian Mock, Marcus Jodorf,
-Richard Kettlewell, Yuriy M. Kaminskiy, Bill Parker, Thomas Hochstein
+Richard Kettlewell, Yuriy M. Kaminskiy, Bill Parker, Thomas Hochstein,
+Tanguy Ortolo

Modified: doc/man/libinn.3
===================================================================
--- doc/man/libinn.3	2017-09-18 20:13:08 UTC (rev 10178)
+++ doc/man/libinn.3	2017-09-18 20:13:48 UTC (rev 10179)
@@ -137,7 +137,7 @@
 related data.
 .PP
 .I GenerateMessageID
-uses the current time, process-ID, and fully-qualified domain name, which is
+uses the current time, process-ID, and fully qualified domain name, which is
 passed as an argument and used if local host can not be resolved or it is
 different from ``domain'' set in
 .IR inn.conf ,
@@ -277,7 +277,7 @@
 It returns false on failure or true on success.
 .PP
 .I GetFQDN
-returns the fully-qualified domain name of the local host.
+returns the fully qualified domain name of the local host.
 .I Domain
 is used if local host can not be resolved.
 The returned value points to static space that is reused on subsequent calls,

Modified: doc/man/nnrpd.track.5
===================================================================
--- doc/man/nnrpd.track.5	2017-09-18 20:13:08 UTC (rev 10178)
+++ doc/man/nnrpd.track.5	2017-09-18 20:13:48 UTC (rev 10179)
@@ -27,7 +27,7 @@
 .fi
 .RE
 .PP
-The first field is either the FQDN of a host, or a domain name (in 
+The first field is either one of the FQDNs of a host, or a domain name (in 
 the form *.domain.com).
 .PP
 The second field is simply a segment of text which may be used to

Modified: doc/pod/incoming.conf.pod
===================================================================
--- doc/pod/incoming.conf.pod	2017-09-18 20:13:08 UTC (rev 10178)
+++ doc/pod/incoming.conf.pod	2017-09-18 20:13:48 UTC (rev 10179)
@@ -110,10 +110,11 @@
 =item I<hostname>
 
 This key requires a string value.  It is a list of hostnames separated
-by a comma.  A hostname is the host's fully qualified domain name, or
-the dotted-quad IP address of the peer for IPv4, or the colon-separated IP
-address of the peer for IPv6.  If this key is not present in
-a peer block, the hostname defaults to the label of the peer.
+by a comma.  A hostname is either a fully qualified domain name that
+resolves to the IPv4 or IPv6 address of the peer, or the dotted-quad
+IP address of the peer for IPv4, or the colon-separated IP address
+of the peer for IPv6.  If this key is not present in a peer block,
+the hostname defaults to the label of the peer.
 
 =item I<identd>
 

Modified: doc/pod/inn.conf.pod
===================================================================
--- doc/pod/inn.conf.pod	2017-09-18 20:13:08 UTC (rev 10178)
+++ doc/pod/inn.conf.pod	2017-09-18 20:13:48 UTC (rev 10179)
@@ -60,7 +60,7 @@
 
 This should be the domain name of the local host.  It should not have a
 leading period, and it should not be a full host address.  It is used only
-if the GetFQDN() routine in libinn(3) cannot get the fully-qualified
+if the GetFQDN() routine in libinn(3) cannot get the fully qualified
 domain name by using either the gethostname(3) or gethostbyname(3) calls.
 The check is very simple; if either routine returns a name with a period
 in it, then it is assumed to have the full domain name.  As this parameter
@@ -105,7 +105,7 @@
 including locally posted articles, and is also used when processing some
 control messages and when naming the server in status reports.  There is
 no default value; this parameter must be set in F<inn.conf> or INN will
-not start.  A good value to use is the fully-qualified hostname of the
+not start.  A good value to use is the fully qualified hostname of the
 system.
 
 =item I<runasgroup>
@@ -881,15 +881,17 @@
 
 =item I<addinjectionpostinghost>
 
-Whether to add a posting-host attribute to the Injection-Info: header to
-all local posts giving the FQDN (when known) and IP address of the system
-from which the post was received.  This is a boolean value and the default
-is true.  Note that INN either does not add this attribute or adds the name
-(when known) and IP address of the client.  There is no intrinsic support for
-obfuscating the name of the client.  That has to be done with a user-written
-Perl filter, if desired.
+Whether to add a posting-host attribute to the Injection-Info: header
+to all local posts giving an FQDN (when known, by reverse lookup of
+the client IP address) and IP address of the system from which the
+post was received.  This is a boolean value and the default is true.
+Note that INN either does not add this attribute or adds the name (when
+known) and IP address of the client.  There is no intrinsic support
+for obfuscating the name of the client.  That has to be done with a
+user-written Perl filter, if desired.
 
-When this parameter is set to true, the FQDN (or, if unknown, the IP address)
+When this parameter is set to true, an FQDN (obtained by reverse
+lookup of the client IP address or, if unknown, the IP address itself)
 of the client is also added to the Path: header, after the C<!.POSTED>
 diagnostic.
 
@@ -916,7 +918,7 @@
 setting will also be used by mailpost(8) to fully qualify addresses and by
 inews(1) to generate the Sender: header (and From: header if missing).
 The value of the FROMHOST environment variable, if set, overrides this
-setting.  The default is the fully-qualified domain name of the local
+setting.  The default is the fully qualified domain name of the local
 host.
 
 =item I<localmaxartsize>

Modified: doc/pod/innfeed.conf.pod
===================================================================
--- doc/pod/innfeed.conf.pod	2017-09-18 20:13:08 UTC (rev 10178)
+++ doc/pod/innfeed.conf.pod	2017-09-18 20:13:48 UTC (rev 10179)
@@ -680,9 +680,11 @@
 
 =item I<ip-name>
 
-This key requires a word value.  The word is the host's FQDN, or the dotted
-quad IP-address.  If this value is not specified, then the name of the
-peer in the enclosing I<peer> block is taken to also be its I<ip-name>.
+This key requires a word value.  The word is either one of the host's FQDNs,
+or the dotted-quad IP address of the peer for IPv4, or the colon-separated
+IP address of the peer for IPv6.  If this value is not specified, then
+the name of the peer in the enclosing I<peer> block is taken to also
+be its I<ip-name>.
 
 =back
 

Modified: doc/pod/install.pod
===================================================================
--- doc/pod/install.pod	2017-09-18 20:13:08 UTC (rev 10178)
+++ doc/pod/install.pod	2017-09-18 20:13:48 UTC (rev 10179)
@@ -818,13 +818,14 @@
 
 =item pathhost
 
-This is the name of your news server as you wish it to appear in the Path:
-header of all postings which travel through your server (this includes
-local posts and incoming posts that you forward out to other sites).  If
-this parameter is unspecified, the fully-qualified domain name (FQDN) of
-the machine will be used instead.  Please use the FQDN of your server or
-an alias for your server unless you have a very good reason not to; a
-future version of the news RFCs may require this.
+This is the name of your news server as you wish it to appear in
+the Path: header of all postings which travel through your server
+(this includes local posts and incoming posts that you forward out to
+other sites).  If this parameter is unspecified, the fully qualified
+domain name (FQDN) of the machine, as reported by the operating system,
+will be used instead.  Please use the canonical FQDN of your server or
+an alias unless you have a very good reason not to; a future version
+of the news RFCs may require this.
 
 =item rlimitnofile
 

Modified: doc/pod/news.pod
===================================================================
--- doc/pod/news.pod	2017-09-18 20:13:08 UTC (rev 10178)
+++ doc/pod/news.pod	2017-09-18 20:13:48 UTC (rev 10179)
@@ -1171,7 +1171,7 @@
 =item *
 
 Fixed a bug in B<innreport> leading to incorrect summing of B<innd> stats
-when I<hostname> was set to an IPv6 address instead of a fully-qualified
+when I<hostname> was set to an IPv6 address instead of a fully qualified
 domain name.  Thanks to Petr Novopashenniy for the bug report.
 
 =item *

Modified: doc/pod/nnrpd.pod
===================================================================
--- doc/pod/nnrpd.pod	2017-09-18 20:13:08 UTC (rev 10178)
+++ doc/pod/nnrpd.pod	2017-09-18 20:13:48 UTC (rev 10179)
@@ -194,9 +194,10 @@
 
 Replace the paths with something appropriate to your INN installation.
 This will create a self-signed certificate that will expire in a year.
-The B<openssl> program will ask you a variety of questions about your
-organization.  Enter the fully qualified domain name of the server as the
-name the certificate is for.
+The B<openssl> program will ask you a variety of questions about
+your organization.  Enter the fully qualified domain name of your news
+service (either the server canonical name or a dedicated alias for the
+news service) as the name the certificate is for.
 
 You then have to set these F<inn.conf> parameters with the right paths:
 

Modified: lib/getfqdn.c
===================================================================
--- lib/getfqdn.c	2017-09-18 20:13:08 UTC (rev 10178)
+++ lib/getfqdn.c	2017-09-18 20:13:48 UTC (rev 10179)
@@ -11,7 +11,8 @@
 
 
 /*
-**  Get the fully-qualified domain name for this host.
+**  Get the fully qualified domain name for this host, as reported
+**  by the system.
 */
 char *GetFQDN(char *domain)
 {

Modified: nnrpd/auth-ext.c
===================================================================
--- nnrpd/auth-ext.c	2017-09-18 20:13:08 UTC (rev 10178)
+++ nnrpd/auth-ext.c	2017-09-18 20:13:48 UTC (rev 10179)
@@ -30,7 +30,7 @@
 /*
 **  Given the client information struct, a string indicating the program to
 **  run (possibly including arguments) and the directory in which to look for
-**  the command if it's not fully-qualified, start that program and return a
+**  the command if it's not fully qualified, start that program and return a
 **  struct process providing the PID and file descriptors.
 */
 static struct process *

Modified: samples/incoming.conf
===================================================================
--- samples/incoming.conf	2017-09-18 20:13:08 UTC (rev 10178)
+++ samples/incoming.conf	2017-09-18 20:13:48 UTC (rev 10179)
@@ -91,9 +91,10 @@
 ##
 ##  hostname:
 ##   This key is mandatory in a peer block.  The value is a string representing
-##   a list of hostnames separated by a comma.  A hostname is the host's FQDN,
-##   or the dotted-quad IP address of the peer for IPv4, or the colon-separated
-##   IP address of the peer for IPv6.
+##   a list of hostnames separated by a comma.  A hostname is either a FQDN
+##   that resolves to the IPv4 or IPv6 address of the peer, or the dotted-quad
+##   IP address of the peer for IPv4, or the colon-separated IP address of
+##   the peer for IPv6.
 ##
 ##  streaming:
 ##   This key requires a boolean value.  It defines whether streaming commands

Modified: samples/nntpsend.ctl
===================================================================
--- samples/nntpsend.ctl	2017-09-18 20:13:08 UTC (rev 10178)
+++ samples/nntpsend.ctl	2017-09-18 20:13:48 UTC (rev 10179)
@@ -6,7 +6,7 @@
 ##    site:fqdn:max_size:[<args...>]
 ##      <site>        The name used in the newsfeeds file for this site;
 ##                    this determines the name of the batch file.
-##      <fqdn>        The fully-qualified domain name of the site,
+##      <fqdn>        A fully qualified domain name for the site,
 ##                    passed as the parameter to innxmit.
 ##      <size>        Size to truncate batch file if it gets too big;
 ##                    see shrinkfile(1).



More information about the inn-committers mailing list