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.

diff --git a/man/ostree-prepare-root.xml b/man/ostree-prepare-root.xml
index 03bf022e27abc4594a92e35119973c1425784a54..53aad8cdd944eab97c825396450c483690975688 100644 (file)
--- 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 c2a9a8cdb65a20404e87bfdb490462e9657e5d6b..1cebbba100b37e93f81d65405067cb87953c3d6b 100644 (file)
--- 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