pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedDocumentation of .pgpass for Unix is incomplete
7+ messages / 4 participants
[nested] [flat]
* Documentation of .pgpass for Unix is incomplete
@ 2024-08-08 09:44 PG Doc comments form <noreply@postgresql.org>
2024-08-20 00:06 ` Re: Documentation of .pgpass for Unix is incomplete Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 7+ messages in thread
From: PG Doc comments form @ 2024-08-08 09:44 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: marc@msys.ch
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.
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Documentation of .pgpass for Unix is incomplete
2024-08-08 09:44 Documentation of .pgpass for Unix is incomplete PG Doc comments form <noreply@postgresql.org>
@ 2024-08-20 00:06 ` Bruce Momjian <bruce@momjian.us>
2024-08-20 00:42 ` Re: Documentation of .pgpass for Unix is incomplete David G. Johnston <david.g.johnston@gmail.com>
2024-08-20 07:24 ` Re: Documentation of .pgpass for Unix is incomplete Marc Balmer <marc@msys.ch>
0 siblings, 2 replies; 7+ messages in thread
From: Bruce Momjian @ 2024-08-20 00:06 UTC (permalink / raw)
To: marc@msys.ch; pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Documentation of .pgpass for Unix is incomplete
2024-08-08 09:44 Documentation of .pgpass for Unix is incomplete PG Doc comments form <noreply@postgresql.org>
2024-08-20 00:06 ` Re: Documentation of .pgpass for Unix is incomplete Bruce Momjian <bruce@momjian.us>
@ 2024-08-20 00:42 ` David G. Johnston <david.g.johnston@gmail.com>
2024-10-16 20:54 ` Re: Documentation of .pgpass for Unix is incomplete Bruce Momjian <bruce@momjian.us>
1 sibling, 1 reply; 7+ messages in thread
From: David G. Johnston @ 2024-08-20 00:42 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: marc@msys.ch; pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Documentation of .pgpass for Unix is incomplete
2024-08-08 09:44 Documentation of .pgpass for Unix is incomplete PG Doc comments form <noreply@postgresql.org>
2024-08-20 00:06 ` Re: Documentation of .pgpass for Unix is incomplete Bruce Momjian <bruce@momjian.us>
2024-08-20 00:42 ` Re: Documentation of .pgpass for Unix is incomplete David G. Johnston <david.g.johnston@gmail.com>
@ 2024-10-16 20:54 ` Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 7+ messages in thread
From: Bruce Momjian @ 2024-10-16 20:54 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: marc@msys.ch; pgsql-docs@lists.postgresql.org
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?"
Attachments:
[text/x-diff] home.diff (2.3K, ../../ZxAoE-V74KRR26Jb@momjian.us/2-home.diff)
download | inline diff:
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index afc9346757a..bfefb1289e8 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -9256,7 +9256,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
The file <filename>.pgpass</filename> in a user's home directory can
contain passwords to
be used if the connection requires a password (and no password has been
- specified otherwise). On Microsoft Windows the file is named
+ specified otherwise). On Unix systems, the directory can be specified by
+ the <envar>HOME</envar> environment variable, or if undefined, the home
+ directory of the effective user. On Microsoft Windows the file is named
<filename>%APPDATA%\postgresql\pgpass.conf</filename> (where
<filename>%APPDATA%</filename> refers to the Application Data subdirectory in
the user's profile).
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 627bb5ab5cc..188e8f0b4d0 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -194,7 +194,9 @@ OPTIONS (ADD password_required 'false');
user can potentially use any client certificates,
<filename>.pgpass</filename>,
<filename>.pg_service.conf</filename> etc. in the unix home directory of the
- system user the postgres server runs as. They can also use any trust
+ system user the postgres server runs as. (For details on how home
+ directories are found, see <xref linkend="libpq-pgpass"/>.) They can
+ also use any trust
relationship granted by authentication modes like <literal>peer</literal>
or <literal>ident</literal> authentication.
</para>
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index b825ca96a23..e42073ed748 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1048,7 +1048,8 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1
<para>
Changes the current working directory to
<replaceable>directory</replaceable>. Without argument, changes
- to the current user's home directory.
+ to the current user's home directory. For details on how home
+ directories are found, see <xref linkend="libpq-pgpass"/>.
</para>
<tip>
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Documentation of .pgpass for Unix is incomplete
2024-08-08 09:44 Documentation of .pgpass for Unix is incomplete PG Doc comments form <noreply@postgresql.org>
2024-08-20 00:06 ` Re: Documentation of .pgpass for Unix is incomplete Bruce Momjian <bruce@momjian.us>
@ 2024-08-20 07:24 ` Marc Balmer <marc@msys.ch>
2024-11-01 17:32 ` Re: Documentation of .pgpass for Unix is incomplete Bruce Momjian <bruce@momjian.us>
1 sibling, 1 reply; 7+ messages in thread
From: Marc Balmer @ 2024-08-20 07:24 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: pgsql-docs@lists.postgresql.org
> 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…
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Documentation of .pgpass for Unix is incomplete
2024-08-08 09:44 Documentation of .pgpass for Unix is incomplete PG Doc comments form <noreply@postgresql.org>
2024-08-20 00:06 ` Re: Documentation of .pgpass for Unix is incomplete Bruce Momjian <bruce@momjian.us>
2024-08-20 07:24 ` Re: Documentation of .pgpass for Unix is incomplete Marc Balmer <marc@msys.ch>
@ 2024-11-01 17:32 ` Bruce Momjian <bruce@momjian.us>
2024-11-01 17:58 ` Re: Documentation of .pgpass for Unix is incomplete Marc Balmer <marc@msys.ch>
0 siblings, 1 reply; 7+ messages in thread
From: Bruce Momjian @ 2024-11-01 17:32 UTC (permalink / raw)
To: Marc Balmer <marc@msys.ch>; +Cc: pgsql-docs@lists.postgresql.org
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?"
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Documentation of .pgpass for Unix is incomplete
2024-08-08 09:44 Documentation of .pgpass for Unix is incomplete PG Doc comments form <noreply@postgresql.org>
2024-08-20 00:06 ` Re: Documentation of .pgpass for Unix is incomplete Bruce Momjian <bruce@momjian.us>
2024-08-20 07:24 ` Re: Documentation of .pgpass for Unix is incomplete Marc Balmer <marc@msys.ch>
2024-11-01 17:32 ` Re: Documentation of .pgpass for Unix is incomplete Bruce Momjian <bruce@momjian.us>
@ 2024-11-01 17:58 ` Marc Balmer <marc@msys.ch>
0 siblings, 0 replies; 7+ messages in thread
From: Marc Balmer @ 2024-11-01 17:58 UTC (permalink / raw)
To: Momjian Bruce <bruce@momjian.us>; +Cc: pgsql-docs@lists.postgresql.org
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?"
^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2024-11-01 17:58 UTC | newest]
Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2024-08-08 09:44 Documentation of .pgpass for Unix is incomplete PG Doc comments form <noreply@postgresql.org>
2024-08-20 00:06 ` Bruce Momjian <bruce@momjian.us>
2024-08-20 00:42 ` David G. Johnston <david.g.johnston@gmail.com>
2024-10-16 20:54 ` Bruce Momjian <bruce@momjian.us>
2024-08-20 07:24 ` Marc Balmer <marc@msys.ch>
2024-11-01 17:32 ` Bruce Momjian <bruce@momjian.us>
2024-11-01 17:58 ` Marc Balmer <marc@msys.ch>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox