Skip to content

Commit

Permalink
Split dsik layout section into its own page
Browse files Browse the repository at this point in the history
  • Loading branch information
@travier
travier committed Jun 7, 2023
1 parent dde2892 commit acbf3da
Show file tree
Hide file tree
Showing 3 changed files with 67 additions and 67 deletions.
1 change: 1 addition & 0 deletions modules/ROOT/nav.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
65 changes: 65 additions & 0 deletions modules/ROOT/pages/disk-layout.adoc
View file
Original file line number Diff line number Diff line change
@@ -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-<number>`, `root`, `root-<number>`, `BIOS-BOOT`, `bios-<number>`, `EFI-SYSTEM`, and `esp-<number>` 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.
68 changes: 1 addition & 67 deletions modules/ROOT/pages/storage.adoc
View file
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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-<number>`, `root`, `root-<number>`, `BIOS-BOOT`, `bios-<number>`, `EFI-SYSTEM`, and `esp-<number>` 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.

0 comments on commit acbf3da

Please sign in to comment.