[Patch] Clarify incoming peer hostname meaning

[Julien ÉLIE]

Hi Tanguy,

> While configuring a personal new server for the first time, I had
> some doubts about how INN processes the hostname parameter in peer
> definitions in incoming.conf. Indeed, the incoming.conf(5) manpage
> indicates this is the peer FQDN, but a host is likely to have several
> FQDNs
Thanks for your message.
I believe other parts of the documentation should be fixed with regards
to use of the "FQDN" terminology.
Does the following suggestion look good to you?

When using getaddrinfo() or the "hostname" Linux command, does it mean
that the result can differ between two calls?  (when the hostname has
several FQDNs)



Index: doc/man/libinn.3
===================================================================
--- doc/man/libinn.3	(révision 10171)
+++ doc/man/libinn.3	(copie de travail)
@@ -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 one of the fully qualified domain names 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,
Index: doc/man/nnrpd.track.5
===================================================================
--- doc/man/nnrpd.track.5	(révision 10171)
+++ doc/man/nnrpd.track.5	(copie de travail)
@@ -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
Index: doc/pod/incoming.conf.pod
===================================================================
--- doc/pod/incoming.conf.pod	(révision 10171)
+++ doc/pod/incoming.conf.pod	(copie de travail)
@@ -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>
 
Index: doc/pod/inn.conf.pod
===================================================================
--- doc/pod/inn.conf.pod	(révision 10171)
+++ doc/pod/inn.conf.pod	(copie de travail)
@@ -875,7 +875,7 @@
 =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
+all local posts giving an 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
@@ -882,7 +882,7 @@
 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 (or, if unknown, the IP address)
 of the client is also added to the Path: header, after the C<!.POSTED>
 diagnostic.
 
Index: doc/pod/innfeed.conf.pod
===================================================================
--- doc/pod/innfeed.conf.pod	(révision 10171)
+++ doc/pod/innfeed.conf.pod	(copie de travail)
@@ -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
 
Index: doc/pod/install.pod
===================================================================
--- doc/pod/install.pod	(révision 10171)
+++ doc/pod/install.pod	(copie de travail)
@@ -821,10 +821,10 @@
 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 parameter is unspecified, one of the fully qualified domain names (FQDN)
+of the machine will be used instead.  Please use one of the FQDNs of your
+server unless you have a very good reason not to; a future version of the
+news RFCs may require this.
 
 =item rlimitnofile
 
Index: doc/pod/nnrpd.pod
===================================================================
--- doc/pod/nnrpd.pod	(révision 10171)
+++ doc/pod/nnrpd.pod	(copie de travail)
@@ -195,8 +195,8 @@
 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.
+organization.  Enter one of the fully qualified domain names of the server
+as the name the certificate is for.
 
 You then have to set these F<inn.conf> parameters with the right paths:
 
Index: lib/getfqdn.c
===================================================================
--- lib/getfqdn.c	(révision 10171)
+++ lib/getfqdn.c	(copie de travail)
@@ -11,7 +11,7 @@
 
 
 /*
-**  Get the fully-qualified domain name for this host.
+**  Get one of the fully qualified domain names for this host.
 */
 char *GetFQDN(char *domain)
 {
Index: samples/incoming.conf
===================================================================
--- samples/incoming.conf	(révision 10171)
+++ samples/incoming.conf	(copie de travail)
@@ -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
Index: samples/nntpsend.ctl
===================================================================
--- samples/nntpsend.ctl	(révision 10171)
+++ samples/nntpsend.ctl	(copie de travail)
@@ -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).



-- 
Julien ÉLIE

« Du moment qu'on rit des choses, elles ne sont plus dangereuses. »
  (Raymond Devos)