Thread: Documentation of .pgpass for Unix is incomplete
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.
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:
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.)
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 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! > Am 01.11.2024 um 18:32 schrieb Bruce Momjian <bruce@momjian.us>: > > 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?"