From: Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Date: Mon, 11 Oct 2021 18:56:07 +0000 (+0200)
Subject: man: adjust the description of ReadOnly
X-Git-Tag: v11~30
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fdaa2156968817d0dbbcdd32cc3f9357315316c2;p=thirdparty%2Fmkosi.git

man: adjust the description of ReadOnly

The reader might think that the flag actually enforces this somehow,
but it's just a hint that is easy to ignore.

Inspired by https://github.com/systemd/mkosi/issues/821.
---

diff --git a/man/mkosi.1 b/man/mkosi.1
index 2f157f4b8..1f7ba9178 100644
--- a/man/mkosi.1
+++ b/man/mkosi.1
@@ -497,10 +497,15 @@ SecureBoot keys via mkosi\[cq]s \f[C]genkey\f[R] command.
 Defaults to two years (730 days).
 .TP
 \f[B]\f[CB]ReadOnly=\f[B]\f[R], \f[B]\f[CB]--read-only\f[B]\f[R]
-Make root file system read-only.
+Set the read-only flag on the root partition in the partition table.
 Only applies to \f[C]gpt_ext4\f[R], \f[C]gpt_xfs\f[R],
 \f[C]gpt_btrfs\f[R], \f[C]subvolume\f[R] output formats, and is implied
 on \f[C]gpt_squashfs\f[R] and \f[C]plain_squashfs\f[R].
+The read-only flag is essentially a hint to tools using the image (see
+https://systemd.io/DISCOVERABLE_PARTITIONS/).
+In particular, all systemd tools like \f[C]systemd-nspawn\f[R] and
+\f[C]systemd-gpt-auto-generator\f[R] will mount such partitions
+read-only, but tools from other project may ignore the flag.
 .TP
 \f[B]\f[CB]Minimize=\f[B]\f[R], \f[B]\f[CB]--minimize\f[B]\f[R]
 Attempt to make the resulting root file system as small as possible by
diff --git a/mkosi.md b/mkosi.md
index dc12dd61e..29a7eaa6a 100644
--- a/mkosi.md
+++ b/mkosi.md
@@ -502,9 +502,17 @@ a boolean argument: either "1", "yes", or "true" to enable, or "0",
 
 `ReadOnly=`, `--read-only`
 
-: Make root file system read-only. Only applies to `gpt_ext4`,
-  `gpt_xfs`, `gpt_btrfs`, `subvolume` output formats, and is implied on
-  `gpt_squashfs` and `plain_squashfs`.
+: Set the read-only flag on the root partition in the partition table.
+  Only applies to `gpt_ext4`, `gpt_xfs`, `gpt_btrfs`, `subvolume`
+  output formats, and is implied on `gpt_squashfs` and `plain_squashfs`.
+
+: The read-only flag is essentially a hint to tools using the image
+  (see https://systemd.io/DISCOVERABLE_PARTITIONS/). In particular,
+  all systemd tools like `systemd-nspawn` and
+  `systemd-gpt-auto-generator` will mount such partitions read-only,
+  but tools from other project may ignore the flag.
+
+[//]: # (Please add external tools to the list here.)
 
 `Minimize=`, `--minimize`