From acbf3da2b176da3d1364a42f98a24c538d0abf05 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Ravier?= Date: Wed, 24 May 2023 19:53:44 +0200 Subject: [PATCH] Split dsik layout section into its own page --- modules/ROOT/nav.adoc | 1 + modules/ROOT/pages/disk-layout.adoc | 65 +++++++++++++++++++++++++++ modules/ROOT/pages/storage.adoc | 68 +---------------------------- 3 files changed, 67 insertions(+), 67 deletions(-) create mode 100644 modules/ROOT/pages/disk-layout.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 91f8a6d3..1e466857 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -24,6 +24,7 @@ ** link:https://coreos.github.io/butane/specs/[Butane Specification] ** xref:remote-ign.adoc[Using a remote Ignition config] * Storage Configuration +** xref:disk-layout.adoc[Default layout] ** xref:storage.adoc[Configuring Storage] * Network Configuration ** xref:sysconfig-network-configuration.adoc[Network Configuration] diff --git a/modules/ROOT/pages/disk-layout.adoc b/modules/ROOT/pages/disk-layout.adoc new file mode 100644 index 00000000..98ddabc2 --- /dev/null +++ b/modules/ROOT/pages/disk-layout.adoc @@ -0,0 +1,65 @@ += Default disk layout, partition tables and filesystems and mount points + +All Fedora CoreOS systems start with the same disk image which varies slightly between architectures based on what is needed for bootloading. On first boot the root filesystem is expanded to fill the rest of the disk. The disk image can be customized using Butane configs to repartition the disk and create/reformat filesystems. Bare metal installations are not different; the installer only copies the raw image to the target disk and injects the specified config into `/boot` for use on first boot. + +NOTE: See xref:storage.adoc#_reconfiguring_the_root_filesystem[Reconfiguring the root filesystem] for examples regarding the supported changes to the root partition. + +== Partition Tables + +Using partition numbers to refer to specific partitions is discouraged and labels or UUIDs should be used instead. Fedora CoreOS reserves the `boot`, `boot-`, `root`, `root-`, `BIOS-BOOT`, `bios-`, `EFI-SYSTEM`, and `esp-` labels, and the `md-boot` and `md-root` RAID device names. Creating partitions, filesystems, or RAID devices with those labels is not supported. + +== x86_64 Partition Table + +The x86_64 disk image is GPT formatted with a protective MBR. It supports booting via both BIOS and UEFI (including Secure Boot). + +The partition table layout has changed over time. The current layout is: + +.Partition Table for x86_64 +|============================================================================================ +| Number | Label | Description | Partition Type +| 1 | BIOS-BOOT | Contains BIOS GRUB image | raw data +| 2 | EFI-SYSTEM | Contains EFI GRUB image and Secure Boot shim | FAT32 +| 3 | boot | Contains GRUB configuration, kernel/initramfs images | ext4 +| 4 | root | Contains the root filesystem | xfs +|============================================================================================ + +The EFI-SYSTEM partition can be deleted or reformatted when BIOS booting. Similarly, the BIOS-BOOT partition can be deleted or reformatted when EFI booting. + +== Mounted Filesystems + +Fedora CoreOS uses OSTree, which is a system for managing multiple bootable operating system trees that share storage. This is distinct from e.g. Container Linux which used a dual partition system. In Fedora CoreOS each operating system version is part of the `/` filesystem. All deployments share the same `/var` which can be on the same filesystem, or mounted separately. + +This shows the default mountpoints for a Fedora CoreOS system installed on a `/dev/vda` disk: + +.Default mountpoints on x86_64 +[source,bash] +---- +$ findmnt --real # Some details are elided +TARGET SOURCE FSTYPE OPTIONS +/ /dev/vda4[/ostree/deploy/fedora-coreos/deploy/$hash] xfs rw +|-/sysroot /dev/vda4 xfs ro +|-/etc /dev/vda4[/ostree/deploy/fedora-coreos/deploy/$hash/etc] xfs rw +|-/usr /dev/vda4[/ostree/deploy/fedora-coreos/deploy/$hash/usr] xfs ro +|-/var /dev/vda4[/ostree/deploy/fedora-coreos/deploy/var] xfs rw +`-/boot /dev/vda3 ext4 ro +---- + +The EFI System Partition was formerly mounted on `/boot/efi`, but this is no longer the case. On systems configured with boot device mirroring, there are independent EFI partitions on each constituent disk. + +== Immutable `/`, read only `/usr` + +As OSTree is used to manage all files belonging to the operating system, the `/` and `/usr` mountpoints are not writable. Any changes to the operating system should be applied via https://coreos.github.io/rpm-ostree/administrator-handbook/[`rpm-ostree`]. + +Similarly, the `/boot` mountpoint is not writable, and the EFI System Partition is not mounted by default. These filesystems are managed by `rpm-ostree` and `bootupd`, and must not be directly modified by an administrator. + +Adding top level directories (i.e. `/foo`) is currently unsupported and disallowed by the immutable attribute. + +The *real* `/` (as in the root of the filesystem in the `root` partition) is mounted readonly in `/sysroot` and must not be accessed or modified directly. + +== Configuration in `/etc` and state in `/var` + +The only supported writable locations are `/etc` and `/var`. `/etc` should contain only configuration files and is not expected to store data. All data must be kept under `/var` and will not be touched by system upgrades. Traditional places that might hold state (e.g. `/home`, or `/srv`) are symlinks to directories in `/var` (e.g. `/var/home` or `/var/srv`). + +== Version selection and bootup + +A GRUB menu entry is created for each version of Fedora CoreOS currently available on a system. This menu entry references an `ostree` deployment which consists of a Linux kernel, an initramfs and a hash linking to an `ostree` commit (passed via the `ostree=` kernel argument). During bootup, `ostree` will read this kernel argument to determine which deployment to use as the root filesystem. Each update or change to the system (package installation, addition of kernel arguments) creates a new deployment. This enables rolling back to a previous deployment if the update causes problems. diff --git a/modules/ROOT/pages/storage.adoc b/modules/ROOT/pages/storage.adoc index 49cd57e8..08379106 100644 --- a/modules/ROOT/pages/storage.adoc +++ b/modules/ROOT/pages/storage.adoc @@ -1,6 +1,6 @@ = Configuring Storage -Fedora CoreOS ships with a simple default storage layout: the root partition is the last one and expands to take the full size of the disk. Apart from the boot partition, all data is stored on the root partition. See the xref:#_disk_layout[Disk layout section] for more details. +Fedora CoreOS ships with a simple default storage layout: the root partition is the last one and expands to take the full size of the disk. Apart from the boot partition, all data is stored on the root partition. See the xref:disk-layout.adoc[Disk layout] page for more details. Below, we provide examples of various ways you can customize this. @@ -547,69 +547,3 @@ storage: wipe_filesystem: true with_mount_unit: true ---- - -== Disk Layout - -All Fedora CoreOS systems start with the same disk image which varies slightly between architectures based on what is needed for bootloading. On first boot the root filesystem is expanded to fill the rest of the disk. The disk image can be customized using Butane configs to repartition the disk and create/reformat filesystems. Bare metal installations are not different; the installer only copies the raw image to the target disk and injects the specified config into `/boot` for use on first boot. - -NOTE: See xref:#_reconfiguring_the_root_filesystem[Reconfiguring the root filesystem] for examples regarding the supported changes to the root partition. - -=== Partition Tables - -Using partition numbers to refer to specific partitions is discouraged and labels or UUIDs should be used instead. Fedora CoreOS reserves the `boot`, `boot-`, `root`, `root-`, `BIOS-BOOT`, `bios-`, `EFI-SYSTEM`, and `esp-` labels, and the `md-boot` and `md-root` RAID device names. Creating partitions, filesystems, or RAID devices with those labels is not supported. - -=== x86_64 Partition Table - -The x86_64 disk image is GPT formatted with a protective MBR. It supports booting via both BIOS and UEFI (including Secure Boot). - -The partition table layout has changed over time. The current layout is: - -.Partition Table for x86_64 -|============================================================================================ -| Number | Label | Description | Partition Type -| 1 | BIOS-BOOT | Contains BIOS GRUB image | raw data -| 2 | EFI-SYSTEM | Contains EFI GRUB image and Secure Boot shim | FAT32 -| 3 | boot | Contains GRUB configuration, kernel/initramfs images | ext4 -| 4 | root | Contains the root filesystem | xfs -|============================================================================================ - -The EFI-SYSTEM partition can be deleted or reformatted when BIOS booting. Similarly, the BIOS-BOOT partition can be deleted or reformatted when EFI booting. - -== Mounted Filesystems - -Fedora CoreOS uses OSTree, which is a system for managing multiple bootable operating system trees that share storage. This is distinct from e.g. Container Linux which used a dual partition system. In Fedora CoreOS each operating system version is part of the `/` filesystem. All deployments share the same `/var` which can be on the same filesystem, or mounted separately. - -This shows the default mountpoints for a Fedora CoreOS system installed on a `/dev/vda` disk: - -.Default mountpoints on x86_64 -[source,bash] ----- -$ findmnt --real # Some details are elided -TARGET SOURCE FSTYPE OPTIONS -/ /dev/vda4[/ostree/deploy/fedora-coreos/deploy/$hash] xfs rw -|-/sysroot /dev/vda4 xfs ro -|-/etc /dev/vda4[/ostree/deploy/fedora-coreos/deploy/$hash/etc] xfs rw -|-/usr /dev/vda4[/ostree/deploy/fedora-coreos/deploy/$hash/usr] xfs ro -|-/var /dev/vda4[/ostree/deploy/fedora-coreos/deploy/var] xfs rw -`-/boot /dev/vda3 ext4 ro ----- - -The EFI System Partition was formerly mounted on `/boot/efi`, but this is no longer the case. On systems configured with boot device mirroring, there are independent EFI partitions on each constituent disk. - -=== Immutable `/`, read only `/usr` - -As OSTree is used to manage all files belonging to the operating system, the `/` and `/usr` mountpoints are not writable. Any changes to the operating system should be applied via https://coreos.github.io/rpm-ostree/administrator-handbook/[`rpm-ostree`]. - -Similarly, the `/boot` mountpoint is not writable, and the EFI System Partition is not mounted by default. These filesystems are managed by `rpm-ostree` and `bootupd`, and must not be directly modified by an administrator. - -Adding top level directories (i.e. `/foo`) is currently unsupported and disallowed by the immutable attribute. - -The *real* `/` (as in the root of the filesystem in the `root` partition) is mounted readonly in `/sysroot` and must not be accessed or modified directly. - -=== Configuration in `/etc` and state in `/var` - -The only supported writable locations are `/etc` and `/var`. `/etc` should contain only configuration files and is not expected to store data. All data must be kept under `/var` and will not be touched by system upgrades. Traditional places that might hold state (e.g. `/home`, or `/srv`) are symlinks to directories in `/var` (e.g. `/var/home` or `/var/srv`). - -=== Version selection and bootup - -A GRUB menu entry is created for each version of Fedora CoreOS currently available on a system. This menu entry references an `ostree` deployment which consists of a Linux kernel, an initramfs and a hash linking to an `ostree` commit (passed via the `ostree=` kernel argument). During bootup, `ostree` will read this kernel argument to determine which deployment to use as the root filesystem. Each update or change to the system (package installation, addition of kernel arguments) creates a new deployment. This enables rolling back to a previous deployment if the update causes problems.