From b5a10c8421abdcf849b4dee2f0bc67af41e245a1 Mon Sep 17 00:00:00 2001
From: jbtrystram <jbtrystram@redhat.com>
Date: Wed, 4 Sep 2024 11:39:48 +0200
Subject: [PATCH] add a composeFS page

We added composeFS starting in f41. Since it comes with a couple of
drawbacks let's document it and explain how to disable it.

https://github.com/coreos/fedora-coreos-tracker/issues/1718#issuecomment-2326801261
https://github.com/coreos/fedora-coreos-config/pull/3009
---
 modules/ROOT/nav.adoc             |  1 +
 modules/ROOT/pages/composefs.adoc | 46 +++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 modules/ROOT/pages/composefs.adoc

diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc
index 9f1c8081..11924f04 100644
--- a/modules/ROOT/nav.adoc
+++ b/modules/ROOT/nav.adoc
@@ -45,6 +45,7 @@
 ** xref:time-zone.adoc[Configuring Time Zone]
 ** xref:grub-password.adoc[Setting a GRUB password]
 ** xref:audit.adoc[Managing the audit daemon]
+** xref:composefs.adoc[ComposeFS]
 * OS updates
 ** xref:update-streams.adoc[Update Streams]
 ** xref:auto-updates.adoc[Auto-Updates]
diff --git a/modules/ROOT/pages/composefs.adoc b/modules/ROOT/pages/composefs.adoc
new file mode 100644
index 00000000..7ea4afa5
--- /dev/null
+++ b/modules/ROOT/pages/composefs.adoc
@@ -0,0 +1,46 @@
+= ComposeFS
+
+Fedora CoreOS introduced ComposeFS enabled by default starting in Fedora 41. ComposeFS is an overlay filesystem where the data comes from the usual ostree deployement, and
+metadata are in the composeFS file. The result is a truely read-only root (`/`) filesystem, increasing the system integrity and robustness,
+
+This is a first step towards a full verification of filesystem integrity, even at runtime.
+
+== What does it change ? 
+
+The main visible change will be that the root filesystem (/) is now small and full (a few MB, 100% used).
+The real root is mounted in /sysroot and most of the data is stored in /var. 
+
+== How to disable composeFS
+
+ComposeFS can be disabled through a kernel argument: `ostree.prepare-root.composefs=0`.
+
+.Disabling composeFS mount
+[source,yaml,subs="attributes"]
+----
+variant: fcos
+version: {butane-latest-stable-spec}
+kernel_arguments:
+  should_exist:
+    - ostree.prepare-root.composefs=0
+----
+
+== Known issues
+
+=== Kdump
+
+Right now, this prevents kdump from writing the memory dumps as it get confused by the read-only filesystem.
+If you want to use kdump and export kernels dumps to the local machine, composeFS must be disabled.
+The kdump upstream developpers are working on a fix. We will update this page when the workaround is no longer needed.
+
+=== Top-level directories
+
+Another consequence is that it is now impossible to create top-level direcories in `/`. Those are usually mount points.
+There are a few ways around this: 
+ - Disable composeFS as showed above.
+ - Enable transient root by adding `root.transient=true` in `/etc/ostree/prepare-root.conf`. Please note that all changes created
+(even in `/etc`) will be lost on upgrades. More details in https://ostreedev.github.io/ostree/man/ostree-prepare-root.html[ostree documentation].
+ - Derive a container and create your required top-level directories there. 
+
+== Links
+
+https://fedoraproject.org/wiki/Changes/ComposefsAtomicCoreOSIoT