diff --git a/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md b/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md index 9e8472ad..dab4d391 100644 --- a/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md +++ b/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md @@ -24,7 +24,7 @@ Flatcar Container Linux is designed to be reliably updated via a continuous stre For more information, [read more about the disk layout][chromium disk format] used by Chromium and ChromeOS, which inspired the layout used by Flatcar Container Linux. [OEM docs]: ../../installing/community-platforms/notes-for-distributors -[chromium disk format]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/disk_format.md +[chromium disk format]: https://www.chromium.org/chromium-os/developer-library/reference/device/disk-format/ ## Mounted filesystems @@ -32,7 +32,9 @@ Flatcar Container Linux is divided into two main filesystems, a read-only `/usr` ### Read-only /usr -The `USR-A` or `USR-B` partitions are interchangeable and one of the two is mounted as a read-only filesystem at `/usr`. After an update, Flatcar Container Linux will re-configure the GPT priority attribute, instructing the bootloader to boot from the passive (newly updated) partition. Here's an example of the priority flags set on an Amazon EC2 machine: +The `USR-A` or `USR-B` partitions are interchangeable, and one of the two is mounted as a read-only filesystem at `/usr`. + +These partitions each include three flags that affect the boot process, `priority`, `tries`, and `successful`. Their behaviour is fully described in the [manual rollback documentation][manual rollback docs]. Their behaviour is implemented in an [add-gpt-partition-scheme GRUB patch][GRUB patches]. After an update, Flatcar Container Linux will re-configure the GPT priority attribute, instructing the bootloader to boot from the passive (newly updated) partition. Here's an example of the priority flags set on an Amazon EC2 machine: ```shell $ sudo cgpt show /dev/xvda @@ -45,8 +47,19 @@ $ sudo cgpt show /dev/xvda Flatcar Container Linux images ship with the `USR-B` partition empty to reduce the image filesize. The first Flatcar Container Linux update will populate it and start the normal active/passive scheme. +As described in the [supply chain documentation][supply chain docs], these partitions are validated for security using `dm-verity`. The verity hash is stored at a well-known but otherwise unused location within the kernel. The hash is written into the kernel by the [build_image script][verity hash code]. It is then automatically injected into the kernel command line by GRUB, as implemented in this [add-verity-hash GRUB patch][GRUB patches]. + +The chosen partition is initially mounted at `/sysusr` by the initrd using [Flatcar-specific dracut modules][dracut modules]. Some boot process tools, such as Ignition, are too large to store in the initrd, so they are run from this mount point instead via wrappers generated by [this module][wrapper generator]. + The OEM partition is mounted at `/usr/share/oem`. +[manual rollback docs]: ../../setup/debug/manual-rollbacks +[GRUB patches]: https://github.com/flatcar/scripts/tree/main/sdk_container/src/third_party/coreos-overlay/sys-boot/grub/files +[supply chain docs]: ../supply-chain +[verity hash code]: https://github.com/flatcar/scripts/blob/17ea3f2265df0c146b4b811eb9fad1abe35b21a2/build_library/build_image_util.sh#L820-L827 +[dracut modules]: https://github.com/flatcar/bootengine/tree/flatcar-master/dracut +[wrapper generator]: https://github.com/flatcar/bootengine/blob/flatcar-master/dracut/30ignition/module-setup.sh + ### Stateful root All stateful data, including container images, is stored within the read/write filesystem mounted at `/`. On first boot, the ROOT partition and filesystem will expand to fill any remaining free space at the end of the drive. @@ -54,6 +67,3 @@ All stateful data, including container images, is stored within the read/write f The data stored on the root partition isn't manipulated by the update process. In return, we do our best to prevent you from modifying the data in /usr. Due to the unique disk layout of Flatcar Container Linux, `umount -l /etc && rm -rf --one-file-system --no-preserve-root /` is an unsupported but valid operation to purge any OS data. On the next boot, the machine should just start from a clean state, but note that you should rather use the `flatcar-reset` tool for a proper reset, which also gives control of what data to keep. - -[provisioning]: ../../provisioning -[boot process]: ../../provisioning/ignition/boot-process