From e434ded958412335dc0a8f66aaa7536527a8b362 Mon Sep 17 00:00:00 2001 From: James Le Cuirot Date: Mon, 6 May 2024 15:47:30 +0100 Subject: [PATCH 1/6] docs: Update link to ChromiumOS disk format It has moved. --- .../latest/reference/developer-guides/sdk-disk-partitions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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..560c7c26 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 From 3545a89bc77fe328059e58a929c550842e9b30c1 Mon Sep 17 00:00:00 2001 From: James Le Cuirot Date: Mon, 6 May 2024 16:06:22 +0100 Subject: [PATCH 2/6] docs: Delete orphaned links in developer section --- .../latest/reference/developer-guides/sdk-disk-partitions.md | 3 --- 1 file changed, 3 deletions(-) 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 560c7c26..d705fdd1 100644 --- a/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md +++ b/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md @@ -54,6 +54,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 From 78519fc2b99f1a8acaf674b94c6ef4d2a2bab48c Mon Sep 17 00:00:00 2001 From: James Le Cuirot Date: Mon, 6 May 2024 15:58:23 +0100 Subject: [PATCH 3/6] docs: Add more developer notes about the GPT flags --- .../reference/developer-guides/sdk-disk-partitions.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) 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 d705fdd1..afd2318a 100644 --- a/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md +++ b/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md @@ -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 @@ -47,6 +49,9 @@ Flatcar Container Linux images ship with the `USR-B` partition empty to reduce t 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 + ### 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. From d2f0a94622abf670f9508752ec0215d3fc2df255 Mon Sep 17 00:00:00 2001 From: James Le Cuirot Date: Mon, 6 May 2024 17:02:30 +0100 Subject: [PATCH 4/6] docs: Add more detail about dm-verity for devs --- .../latest/reference/developer-guides/sdk-disk-partitions.md | 4 ++++ 1 file changed, 4 insertions(+) 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 afd2318a..0283c7c8 100644 --- a/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md +++ b/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md @@ -47,10 +47,14 @@ $ 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 initrd. The hash is written into the initrd 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 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 ### Stateful root From fb086901516c39ff5124032f3ed87e6eea6235bd Mon Sep 17 00:00:00 2001 From: James Le Cuirot Date: Mon, 6 May 2024 17:40:00 +0100 Subject: [PATCH 5/6] docs: Mention /sysusr mount in developer section --- .../latest/reference/developer-guides/sdk-disk-partitions.md | 4 ++++ 1 file changed, 4 insertions(+) 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 0283c7c8..bef96f3b 100644 --- a/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md +++ b/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md @@ -49,12 +49,16 @@ Flatcar Container Linux images ship with the `USR-B` partition empty to reduce t 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 initrd. The hash is written into the initrd 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 From 62742751876dcdb4f4293a942a0bff0d0ae5eb20 Mon Sep 17 00:00:00 2001 From: James Le Cuirot Date: Tue, 7 May 2024 09:57:10 +0100 Subject: [PATCH 6/6] docs: Correct initrd/kernel reference in dev guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Kai Lüke --- .../latest/reference/developer-guides/sdk-disk-partitions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 bef96f3b..dab4d391 100644 --- a/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md +++ b/content/docs/latest/reference/developer-guides/sdk-disk-partitions.md @@ -47,7 +47,7 @@ $ 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 initrd. The hash is written into the initrd 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]. +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].