From 02587b56760db2a45dcc4b4f97fab7fe86292bc0 Mon Sep 17 00:00:00 2001
From: Ryan Brue <ryanbrue.dev@gmail.com>
Date: Mon, 8 Sep 2025 12:13:09 -0500
Subject: [PATCH] flatpak-metadata: Note host-root symlink pitfalls

Following symlinks from /run/host/root naively (for example, with
realpath()) is wrong.

This commit warns about this problem, and provides examples of how to
avoid it when using the host-root permission, either by using
https://man7.org/linux/man-pages/man2/openat2.2.html for modern kernels,
or https://gitlab.steamos.cloud/steamrt/steam-runtime-tools/-/blob/65adfdd5fc812aeb5f33986755f6ff72c9612afa/steam-runtime-tools/resolve-in-sysroot.c
for older kernels.

Signed-off-by: Ryan Brue <ryanbrue.dev@gmail.com>
---
 doc/flatpak-metadata.xml | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/doc/flatpak-metadata.xml b/doc/flatpak-metadata.xml
index 79c8594e..ea282ad8 100644
--- a/doc/flatpak-metadata.xml
+++ b/doc/flatpak-metadata.xml
@@ -360,6 +360,25 @@
                                 permissions for applications that need the
                                 entire root filesystem of the host.
                             </para>
+                            <para>
+                                Please note that following symlinks under
+                                <filename>/run/host/root</filename> naively
+                                will result in a wrong path. For example,
+                                using <literal>realpath()</literal> is wrong.
+                                Instead, applications will have to implement
+                                some way of following symlinks in a way that
+                                behaves as if it were chroot'd into
+                                <filename>/run/host/root</filename>.
+                            </para>
+                            <para>
+                                There are a few ways to do this. Modern
+                                kernels support the <ulink url="https://man7.org/linux/man-pages/man2/openat2.2.html">openat2()</ulink>
+                                call with <literal>RESOLVE_IN_ROOT</literal>.
+                                For a more portable solution with support for
+                                older kernels, see the implementation from
+                                the <ulink url="https://gitlab.steamos.cloud/steamrt/steam-runtime-tools/-/blob/65adfdd5fc812aeb5f33986755f6ff72c9612afa/steam-runtime-tools/resolve-in-sysroot.c">steam-runtime-tools</ulink>
+                                as an example.
+                            </para>
                             <para>
                                 Available since 1.17.
                             </para></listitem></varlistentry>