Re: [Libguestfs] [libguestfs PATCH 4/7] docs: clarify sockdir's separation

On 7/14/23 11:42, Richard W.M. Jones wrote: > On Thu, Jul 13, 2023 at 07:10:49PM +0200, Laszlo Ersek wrote: >> There's another reason for separating sockdir from tmpdir, beyond "shorter >> pathnames needed": permissions. For example, passt drops privileges such >> that it cannot access "/tmp", and that restricts both the unix domain >> socket and the PID file of passt. >> >> Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2184967 >> Signed-off-by: Laszlo Ersek <lersek(a)redhat.com&gt; >> --- >> generator/actions_properties.ml | 8 ++++++-- >> fish/guestfish.pod | 4 ++-- >> lib/guestfs.pod | 4 ++-- >> 3 files changed, 10 insertions(+), 6 deletions(-) >> >> diff --git a/generator/actions_properties.ml b/generator/actions_properties.ml >> index f84afb10d674..42eaaa4d81e1 100644 >> --- a/generator/actions_properties.ml >> +++ b/generator/actions_properties.ml >> @@ -595,13 +595,17 @@ Get the handle identifier. See C<guestfs_set_identifier>." }; >> name = "get_sockdir"; added = (1, 33, 8); >> style = RString (RPlainString, "sockdir"), [], []; >> blocking = false; >> - shortdesc = "get the temporary directory for sockets"; >> + shortdesc = "get the temporary directory for sockets and PID files"; >> longdesc = "\ >> -Get the directory used by the handle to store temporary socket files. >> +Get the directory used by the handle to store temporary socket and PID >> +files. >> >> This is different from C<guestfs_get_tmpdir>, as we need shorter >> paths for sockets (due to the limited buffers of filenames for UNIX >> sockets), and C<guestfs_get_tmpdir> may be too long for them. >> +Furthermore, sockets and PID files must be accessible to such background >> +services started by libguestfs that may not have permission to access >> +the temporary directory returned by C<guestfs_get_tmpdir>. >> >> The environment variable C<XDG_RUNTIME_DIR> controls the default >> value: If C<XDG_RUNTIME_DIR> is set, then that is the default. >> diff --git a/fish/guestfish.pod b/fish/guestfish.pod >> index ccc0825b84a0..492aa7163fcb 100644 >> --- a/fish/guestfish.pod >> +++ b/fish/guestfish.pod >> @@ -1548,8 +1548,8 @@ See L</LIBGUESTFS_CACHEDIR>, L</LIBGUESTFS_TMPDIR>. >> This directory represents a user-specific directory for storing >> non-essential runtime files. >> >> -If it is set, then is used to store temporary sockets. Otherwise, >> -F</tmp> is used. >> +If it is set, then is used to store temporary sockets and PID files. >> +Otherwise, F</tmp> is used. >> >> See also L</get-sockdir>, > > Although incidental to this change, shouldn't this link also be fixed > in the same way as patch 3? That's the thing: it shouldn't. The generator produces the individual API descriptions for both "guestfish.1" and "guestfs.3". The generator creates one style of anchor (effectively: link name) for "guestfish.1", and another style of anchor for "guestfs.3".

In turn, the "ENVIRONMENT VARIABLES" section is open-coded (not generated), in both "guestfish.pod" and "guestfs.pod" files. So, whenever we insert a link to a generated anchor, in the "ENVIRONMENT VARIABLES" of one of these .pod files, we must use the anchor style that is appropriate for *that particular .pod file*. Commit 55202a4d49a1 had added the same link L</get-sockdir> to the "ENVIRONMENT VARIABLES" section of both .pod files. However, this link style is only good for "guestfish.1". The same link will not work in "guestfs.pod", because it will not match any generated anchor in "guestfs.3". That's why patch#3 only updates "guestfs.pod"; the same link in "guestfish.pod" is not broken.