Thread: BUG #16380: documentation: host[no]gssenc vs. address/IP-address/IP-mask fields

The following bug has been logged on the website:

Bug reference:      16380
Logged by:          Arthur Nascimento
Email address:      tureba@gmail.com
PostgreSQL version: 12.2
Operating system:   Documentation
Description:

Hi,

I see a couple of inconsistencies in the documentation of the pg_hba.conf
file in v12+:
https://www.postgresql.org/docs/12/auth-pg-hba-conf.html (and /current/)

1. Near the top, there's a line saying "A record can have one of the seven
formats", then the followup list shows 9 formats. The ones on host[no]gssenc
were added to the IP-address/IP-mask section, but not to the address
section. I believe the intention was to have 11 lines there, with a
corresponding count at the top.

2. In the address and IP-address/IP-mask descriptions, there's "This field
only applies to host, hostssl, and hostnossl records." and "These fields
only apply to host, hostssl, and hostnossl records.". But those lists should
probably be updated as well to add host[no]gssenc (or to negate the logic,
saying they are not applied to local connections).

Thanks,
Arthur

On Sun, Apr 19, 2020 at 06:29:31PM +0000, PG Bug reporting form wrote:
> The following bug has been logged on the website:
> 
> Bug reference:      16380
> Logged by:          Arthur Nascimento
> Email address:      tureba@gmail.com
> PostgreSQL version: 12.2
> Operating system:   Documentation
> Description:        
> 
> Hi,
> 
> I see a couple of inconsistencies in the documentation of the pg_hba.conf
> file in v12+:
> https://www.postgresql.org/docs/12/auth-pg-hba-conf.html (and /current/)
> 
> 1. Near the top, there's a line saying "A record can have one of the seven
> formats", then the followup list shows 9 formats. The ones on host[no]gssenc
> were added to the IP-address/IP-mask section, but not to the address
> section. I believe the intention was to have 11 lines there, with a
> corresponding count at the top.
> 
> 2. In the address and IP-address/IP-mask descriptions, there's "This field
> only applies to host, hostssl, and hostnossl records." and "These fields
> only apply to host, hostssl, and hostnossl records.". But those lists should
> probably be updated as well to add host[no]gssenc (or to negate the logic,
> saying they are not applied to local connections).

I agree with your suggestions.  I also noticed that pg_hba.conf is
missing gssapi entries too, so I added them to the attached patch. too.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Hi Bruce,

On Tue, 21 Apr 2020 at 15:27, Bruce Momjian <bruce@momjian.us> wrote:
> > 1. Near the top, there's a line saying "A record can have one of the seven
> > formats", then the followup list shows 9 formats. The ones on host[no]gssenc
> > were added to the IP-address/IP-mask section, but not to the address
> > section. I believe the intention was to have 11 lines there, with a
> > corresponding count at the top.
...
> I agree with your suggestions.  I also noticed that pg_hba.conf is
> missing gssapi entries too, so I added them to the attached patch. too.

I thought the list would jump to 11 lines there, meaning 1 local plus
5 on address plus 5 on IP-address/IP-mask.
As it stands now with 9 lines, it's 1 local plus 3 on address (it's
missing the two on host[no]gssenc) plus 5 on IP-address/IP-mask.

Tureba - Arthur Nascimento

On Tue, Apr 21, 2020 at 03:45:47PM -0300, Arthur Nascimento wrote:
> Hi Bruce,
> 
> On Tue, 21 Apr 2020 at 15:27, Bruce Momjian <bruce@momjian.us> wrote:
> > > 1. Near the top, there's a line saying "A record can have one of the seven
> > > formats", then the followup list shows 9 formats. The ones on host[no]gssenc
> > > were added to the IP-address/IP-mask section, but not to the address
> > > section. I believe the intention was to have 11 lines there, with a
> > > corresponding count at the top.
> ...
> > I agree with your suggestions.  I also noticed that pg_hba.conf is
> > missing gssapi entries too, so I added them to the attached patch. too.
> 
> I thought the list would jump to 11 lines there, meaning 1 local plus
> 5 on address plus 5 on IP-address/IP-mask.
> As it stands now with 9 lines, it's 1 local plus 3 on address (it's
> missing the two on host[no]gssenc) plus 5 on IP-address/IP-mask.

Ah, I see.  Updated patch attached.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Hi Bruce,

On Tue, 21 Apr 2020 at 16:08, Bruce Momjian <bruce@momjian.us> wrote:
> Ah, I see.  Updated patch attached.

That looks perfect. Thank you!

Tureba - Arthur Nascimento

> On Tue, 21 Apr 2020 at 16:08, Bruce Momjian <bruce@momjian.us> wrote:
> > Ah, I see.  Updated patch attached.
>
> That looks perfect. Thank you!

Oh, there might be another line to change in the 'address' column.
I see you changed the one under 'IP-address/IP-mask' that starts with
"These fields...".
But there is a similar one under 'address', that starts with "This field...".

Tureba - Arthur Nascimento

On Tue, Apr 21, 2020 at 04:43:19PM -0300, Arthur Nascimento wrote:
> > On Tue, 21 Apr 2020 at 16:08, Bruce Momjian <bruce@momjian.us> wrote:
> > > Ah, I see.  Updated patch attached.
> >
> > That looks perfect. Thank you!
> 
> Oh, there might be another line to change in the 'address' column.
> I see you changed the one under 'IP-address/IP-mask' that starts with
> "These fields...".
> But there is a similar one under 'address', that starts with "This field...".

Agreed, fixed.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Hi,

On Tue, 21 Apr 2020 at 22:17, Bruce Momjian <bruce@momjian.us> wrote:
> Agreed, fixed.

Looks good to me.

Cheers,

Tureba - Arthur Nascimento

On 2020-04-21 21:08, Bruce Momjian wrote:
>     <para>
> -   A record can have one of the seven formats
> +   A record can have one of the 11 formats

I think this sort of thing is a sign that the number should be replaced 
by "several".

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On Tue, Apr 28, 2020 at 04:14:06PM +0200, Peter Eisentraut wrote:
> On 2020-04-21 21:08, Bruce Momjian wrote:
> >     <para>
> > -   A record can have one of the seven formats
> > +   A record can have one of the 11 formats
> 
> I think this sort of thing is a sign that the number should be replaced by
> "several".

Agreed:

-   A record can have one of the 11 formats
+   A record can have several formats:

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

On Tue, Apr 28, 2020 at 01:45:57PM -0400, Bruce Momjian wrote:
> On Tue, Apr 28, 2020 at 04:14:06PM +0200, Peter Eisentraut wrote:
> > On 2020-04-21 21:08, Bruce Momjian wrote:
> > >     <para>
> > > -   A record can have one of the seven formats
> > > +   A record can have one of the 11 formats
> > 
> > I think this sort of thing is a sign that the number should be replaced by
> > "several".
> 
> Agreed:
> 
> -   A record can have one of the 11 formats
> +   A record can have several formats:

Patch applied through PG 12.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

On Sun, Apr 19, 2020 at 06:29:31PM +0000, PG Bug reporting form wrote:
> 1. Near the top, there's a line saying "A record can have one of the seven
> formats", then the followup list shows 9 formats.

Thanks for pointing it out;  it was also mentioned here:
https://www.postgresql.org/message-id/20200505104507.GA32455%40gate.oper.dinoex.org
So I'd included it it in my "docs" patch to resend someday.

-- 
Justin

On Mon, May 25, 2020 at 08:26:47PM -0500, Justin Pryzby wrote:
> On Sun, Apr 19, 2020 at 06:29:31PM +0000, PG Bug reporting form wrote:
> > 1. Near the top, there's a line saying "A record can have one of the seven
> > formats", then the followup list shows 9 formats.
> 
> Thanks for pointing it out;  it was also mentioned here:
> https://www.postgresql.org/message-id/20200505104507.GA32455%40gate.oper.dinoex.org
> So I'd included it it in my "docs" patch to resend someday.

Yes, that was fixed in my patch.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +