Christopher Head wrote:
> On Wed, 14 Jul 2010 18:35:55 -0400
> Tom Lane <[email protected]> wrote:
>
> > Bruce Momjian <[email protected]> writes:
> > > Do the docs need any more updating?
> >
> > No doubt, but it's a bit premature to consider that while we're still
> > arguing whether the code needs to change more.
> >
> > regards, tom lane
> >
>
> Sorry to bother everyone, but AFAICT this discussion kind of
> disappeared. Did I perhaps get dropped from CC? I'm interested to know
> what the final resolution of this is.
>
> My own thought would be:
> "host" means the thing you intended to connect to: a unique identifier
> for the server, probably (usually) the hostname, and also the thing
> that goes in a certificate. Should (probably) never be omitted.
>
> "hostaddr" means the thing you actually send your TCP SYN packet to:
> maybe an IP address if you want to save a DNS lookup, maybe even
> "localhost" if you want to use an SSH tunnel (or even some other
> hostname if you have an even stranger tunnel set up), but purely a
> "network-layer" thing about *how to get to* the server, and not a
> "user-trust-layer" thing about *who the server is*. If omitted,
> defaults to being equal to "host".
>
> I don't know if that's what was intended, but that's what I thought
> they would mean.
I have adjusted the libpq docs to be clearer about 'hostaddr' by using
an itemized list and rewording; attached and applied.
I am not sure what else needs to be done, and I don't think anyone else
knows either, so unless I hear otherwise, I will consider this item
closed. Perhaps the clearer docs will highlight a new open item.
--
Bruce Momjian <[email protected]> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index e78d708..3824588 100644
*** a/doc/src/sgml/libpq.sgml
--- b/doc/src/sgml/libpq.sgml
*************** PGconn *PQconnectdbParams(const char **k
*** 164,185 ****
Using <literal>hostaddr</> instead of <literal>host</> allows the
application to avoid a host name look-up, which might be important
in applications with time constraints. However, a host name is
! required for Kerberos, GSSAPI, or SSPI authentication, as well as
! for full SSL certificate verification. The following rules are
! used:
! If <literal>host</> is specified without <literal>hostaddr</>,
! a host name lookup occurs.
! If <literal>hostaddr</> is specified without <literal>host</>,
! the value for <literal>hostaddr</> gives the server network address.
! The connection attempt will fail in any of the cases where a
! host name is required.
! If both <literal>host</> and <literal>hostaddr</> are specified,
! the value for <literal>hostaddr</> gives the server network address.
! The value for <literal>host</> is ignored unless needed for
! authentication or verification purposes, in which case it will be
! used as the host name. Note that authentication is likely to fail
! if <literal>host</> is not the name of the machine at
! <literal>hostaddr</>.
Also, note that <literal>host</> rather than <literal>hostaddr</>
is used to identify the connection in <filename>~/.pgpass</> (see
<xref linkend="libpq-pgpass">).
--- 164,199 ----
Using <literal>hostaddr</> instead of <literal>host</> allows the
application to avoid a host name look-up, which might be important
in applications with time constraints. However, a host name is
! required for Kerberos, GSSAPI, or SSPI authentication
! methods, as well as for <literal>verify-full</> SSL
! certificate verification. The following rules are used:
! <itemizedlist>
! <listitem>
! <para>
! If <literal>host</> is specified without <literal>hostaddr</>,
! a host name lookup occurs.
! </para>
! </listitem>
! <listitem>
! <para>
! If <literal>hostaddr</> is specified without <literal>host</>,
! the value for <literal>hostaddr</> gives the server network address.
! The connection attempt will fail if the authentication
! method requires a host name.
! </para>
! </listitem>
! <listitem>
! <para>
! If both <literal>host</> and <literal>hostaddr</> are specified,
! the value for <literal>hostaddr</> gives the server network address.
! The value for <literal>host</> is ignored unless the
! authentication method requires it, in which case it will be
! used as the host name.
! </para>
! </listitem>
! </itemizedlist>
! Note that authentication is likely to fail if <literal>host</>
! is not the name of the server at network address <literal>hostaddr</>.
Also, note that <literal>host</> rather than <literal>hostaddr</>
is used to identify the connection in <filename>~/.pgpass</> (see
<xref linkend="libpq-pgpass">).
--
Sent via pgsql-bugs mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-bugs
