From 2cfa8aba7214d81540fa747dfe43192801014048 Mon Sep 17 00:00:00 2001
From: Mark McLoughlin <markmc@redhat.com>
Date: Fri, 24 Nov 2023 14:27:11 +0000
Subject: [PATCH] man: improve sysroot.readonly docs

The explanation of sysroot.readonly is a little confusing - we say
that "everything else is mounted read-only" but it's perhaps clearer
to say /sysroot is mounted read-only.

Also note that read-only is the default with composefs.

Finally, document the option in ostree.repo-config even though it is
now considered legacy - as of commit 22b8e4f9 (#2930) - it is still
commonly seen in repo configs, so users will look to understand
what it means.
---
 man/ostree-prepare-root.xml | 8 ++++----
 man/ostree.repo-config.xml  | 9 +++++++++
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/man/ostree-prepare-root.xml b/man/ostree-prepare-root.xml
index 03bf022e27..53aad8cdd9 100644
--- a/man/ostree-prepare-root.xml
+++ b/man/ostree-prepare-root.xml
@@ -85,10 +85,10 @@ License along with this library. If not, see <https://www.gnu.org/licenses/>.
         </para>
 
         <para>
-            A read-only bind mount is created over <literal>/sysroot/usr</literal>.  The immutable bit is set on the deployment
+            A read-only bind mount is created over <literal>/sysroot/usr</literal>.  The immutable bit (see chattr(1)) is set on the deployment
             root, so this provides basic protection for filesystem mutation.  If the <literal>sysroot.readonly</literal>
-            option is enabled, instead a writable bind mount for <literal>/sysroot/etc</literal>, and everything else
-            is mounted read-only.
+            option is enabled, then <literal>/sysroot/sysroot</literal> is mounted read-only to provide further protection and a writable bind mount for
+            <literal>/sysroot/etc</literal> is created.
         </para>
 
         <para>
@@ -111,7 +111,7 @@ License along with this library. If not, see <https://www.gnu.org/licenses/>.
         <variablelist>
             <varlistentry>
                 <term><varname>sysroot.readonly</varname></term>
-                <listitem><para>A boolean value; the default is <literal>false</literal>.  If this is set to <literal>true</literal>, then the <literal>/sysroot</literal> mount point is mounted read-only.</para></listitem>
+                <listitem><para>A boolean value; the default is <literal>false</literal> unless composefs is enabled.  If this is set to <literal>true</literal>, then the <literal>/sysroot</literal> mount point is mounted read-only.</para></listitem>
             </varlistentry>
             <varlistentry>
                 <term><varname>etc.transient</varname></term>
diff --git a/man/ostree.repo-config.xml b/man/ostree.repo-config.xml
index c2a9a8cdb6..1cebbba100 100644
--- a/man/ostree.repo-config.xml
+++ b/man/ostree.repo-config.xml
@@ -378,6 +378,15 @@ License along with this library. If not, see <https://www.gnu.org/licenses/>.
 
     <variablelist>
 
+      <varlistentry>
+        <term><varname>readonly</varname></term>
+        <listitem><para>A boolean value. If this is set to <literal>true</literal>, then the
+        <literal>/sysroot</literal> mount point is mounted read-only. This is configured a
+        legacy repository configuration and the equivalent option in <literal>ostree/prepare-root.conf</literal>
+        should be used instead - see <citerefentry><refentrytitle>ostree-prepare-root</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+        </para></listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><varname>bootloader</varname></term>
         <listitem><para>Configure the bootloader that OSTree uses when