Documentation of .pgpass for Unix is incomplete

On Thu, Aug 8, 2024 at 09:44:51AM +0000, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/16/libpq-pgpass.html
Description:

The documentation of the .pgpass password file is incomplete in the Unix
case (https://www.postgresql.org/docs/16/libpq-pgpass.html):

It does not mention how the .pgpass File is actually found. One would
assume it uses the getpwent() function to find the current users
homedirectory and locate the .pgpass file there, but this is not the case.
It only looks at the HOME environment variable.

If you change the user using setuid() and do not change HOME as well, the
file not be found. Or assume you start a DB client as root by using su to
change the user id, things will not work:

# /bin/su -c "startx -- " - xpos

This starts X11 and changes to the user xpos, but it does only change the
user id, not $HOME.

Well, it is more complicated than checking just HOME because it calls
getpwuid_r() if HOME is not set:

https://doxygen.postgresql.org/fe-connect_8c.html#a3f49cbb20595c1765bd0db5ff434c9c3

Is it worth going into that detail in the docs?

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

Only you can decide what is important to you.

On Mon, Aug 19, 2024 at 5:06 PM Bruce Momjian <bruce@momjian.us> wrote:

On Thu, Aug 8, 2024 at 09:44:51AM +0000, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/16/libpq-pgpass.html
Description:

The documentation of the .pgpass password file is incomplete in the Unix
case (https://www.postgresql.org/docs/16/libpq-pgpass.html):

It does not mention how the .pgpass File is actually found. One would
assume it uses the getpwent() function to find the current users
homedirectory and locate the .pgpass file there, but this is not the

case.

It only looks at the HOME environment variable.

If you change the user using setuid() and do not change HOME as well, the
file not be found. Or assume you start a DB client as root by using su

to

change the user id, things will not work:

# /bin/su -c "startx -- " - xpos

This starts X11 and changes to the user xpos, but it does only change the
user id, not $HOME.

Well, it is more complicated than checking just HOME because it calls
getpwuid_r() if HOME is not set:

https://doxygen.postgresql.org/fe-connect_8c.html#a3f49cbb20595c1765bd0db5ff434c9c3

Is it worth going into that detail in the docs?

Yes, "the user's home directory" and the "HOME" environment variable are
distinct things. The current docs are wrong.

The .pgpass file, located in $HOME (a.k.a. ~) on non-Microsoft Windows
systems, can contain passwords... In the absence of the HOME environment
variable, the path recorded as the user's home directory in the operating
system's passwd file will be checked. This is not a fallback mechanism -
if HOME is set, and the file is not present there, this directory will not
be checked). On Microsoft Windows... Alternatively, the password file to
use ...

I"m somewhat loath to repeat that in:
https://www.postgresql.org/docs/16/libpq-connect.html#LIBPQ-CONNECT-PASSFILE

passfile
Specifies the name of the file used to store passwords (see Section 34.16).
Defaults to ~/.pgpass, or %APPDATA%\postgresql\pgpass.conf on Microsoft
Windows. (No error is reported if this file does not exist.)

So I'd suggest just removing the talk of defaults, changing it to:

"Specifies the name of the file used to store passwords. See Section 34.16
for details, including the default file name and path resolution mechanics."

David J.

Well, it is more complicated than checking just HOME because it calls
getpwuid_r() if HOME is not set:

https://doxygen.postgresql.org/fe-connect_8c.html#a3f49cbb20595c1765bd0db5ff434c9c3

Is it worth going into that detail in the docs?

Yes definitely. This not being properly documented caused me hours of work…

On Mon, Aug 19, 2024 at 05:42:33PM -0700, David G. Johnston wrote:

On Mon, Aug 19, 2024 at 5:06 PM Bruce Momjian <bruce@momjian.us> wrote:
Well, it is more complicated than checking just HOME because it calls
getpwuid_r() if HOME is not set:

        https://doxygen.postgresql.org/fe-connect_8c.html#
a3f49cbb20595c1765bd0db5ff434c9c3

Is it worth going into that detail in the docs?

Yes, "the user's home directory" and the "HOME" environment variable are
distinct things.  The current docs are wrong.

The .pgpass file, located in $HOME (a.k.a. ~) on non-Microsoft Windows systems,
can contain passwords...  In the absence of the HOME environment variable, the
path recorded as the user's home directory in the operating system's passwd
file will be checked.  This is not a fallback mechanism - if HOME is set, and
the file is not present there, this directory will not be checked).  On
Microsoft Windows... Alternatively, the password file to use ...

I"m somewhat loath to repeat that in:
https://www.postgresql.org/docs/16/libpq-connect.html#LIBPQ-CONNECT-PASSFILE

passfile
Specifies the name of the file used to store passwords (see Section 34.16).
Defaults to ~/.pgpass, or %APPDATA%\postgresql\pgpass.conf on Microsoft
Windows. (No error is reported if this file does not exist.)

So I'd suggest just removing the talk of defaults, changing it to:

"Specifies the name of the file used to store passwords.  See Section 34.16 for
details, including the default file name and path resolution mechanics."

I have written the attached patch to add the home directory details. I
specified in one place and referenced it to two others. Did I miss any
places?

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

When a patient asks the doctor, "Am I going to die?", he means
"Am I going to die soon?"

On Tue, Aug 20, 2024 at 09:24:43AM +0200, Marc Balmer wrote:

Well, it is more complicated than checking just HOME because it calls
getpwuid_r() if HOME is not set:

https://doxygen.postgresql.org/fe-connect_8c.html#a3f49cbb20595c1765bd0db5ff434c9c3

Is it worth going into that detail in the docs?

Yes definitely. This not being properly documented caused me hours of work…

Patch applied, thanks.

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

When a patient asks the doctor, "Am I going to die?", he means
"Am I going to die soon?"

Thanks, Bruce!