Libguestfs - Jul 2023 - [libguestfs PATCH 4/7] docs: clarify sockdir's separation

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 at redhat.com>
---
 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>,
 L<http://www.freedesktop.org/wiki/Specifications/basedir-spec/>.
diff --git a/lib/guestfs.pod b/lib/guestfs.pod
index 68688f31aa5f..e46dd81f9e0a 100644
--- a/lib/guestfs.pod
+++ b/lib/guestfs.pod
@@ -3220,8 +3220,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</guestfs_get_sockdir>,
 L<http://www.freedesktop.org/wiki/Specifications/basedir-spec/>.

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 at redhat.com>
> ---
>  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?
>  L<http://www.freedesktop.org/wiki/Specifications/basedir-spec/>.
> diff --git a/lib/guestfs.pod b/lib/guestfs.pod
> index 68688f31aa5f..e46dd81f9e0a 100644
> --- a/lib/guestfs.pod
> +++ b/lib/guestfs.pod
> @@ -3220,8 +3220,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</guestfs_get_sockdir>,
>  L<http://www.freedesktop.org/wiki/Specifications/basedir-spec/>.
Reviewed-by: Richard W.M. Jones <rjones at redhat.com>

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
Fedora Windows cross-compiler. Compile Windows programs, test, and
build Windows installers. Over 100 libraries supported.
http://fedoraproject.org/wiki/MinGW