Skip to content

Commit

Permalink
add a composeFS page
Browse files Browse the repository at this point in the history
We added composeFS starting in f41. Since it comes with a couple of
drawbacks let's document it and explain how to disable it.

coreos/fedora-coreos-tracker#1718 (comment)
coreos/fedora-coreos-config#3009
  • Loading branch information
jbtrystram committed Sep 4, 2024
1 parent 8bb4e0e commit b5a10c8
Show file tree
Hide file tree
Showing 2 changed files with 47 additions and 0 deletions.
1 change: 1 addition & 0 deletions modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
46 changes: 46 additions & 0 deletions modules/ROOT/pages/composefs.adoc
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit b5a10c8

Please sign in to comment.