Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Re-organize sections #538

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Re-organize sections #538

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
133cddd
Re-organize sections
travier Apr 27, 2023
9b50239
Split dsik layout section into its own page
travier May 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 16 additions & 9 deletions modules/ROOT/nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,28 +19,35 @@
** xref:provisioning-virtualbox.adoc[Booting on VirtualBox]
** xref:provisioning-vmware.adoc[Booting on VMware]
** xref:provisioning-vultr.adoc[Booting on Vultr]
* System Configuration
* Butane and Ignition configs
** xref:producing-ign.adoc[Producing an Ignition File]
** 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]
** xref:managing-files.adoc[Managing Files]
* Network Configuration
** xref:sysconfig-network-configuration.adoc[Network Configuration]
** xref:sysctl.adoc[Kernel Tuning]
** xref:running-containers.adoc[Running Containers]
** xref:authentication.adoc[Configuring Users and Groups]
** xref:hostname.adoc[Setting a Hostname]
** xref:proxy.adoc[Proxied Internet Access]
** xref:sysconfig-setting-keymap.adoc[Setting Keyboard Layout]
** xref:os-extensions.adoc[Adding OS extensions]
** xref:customize-nic.adoc[How to Customize a NIC Name]
** xref:sysconfig-configure-swaponzram.adoc[Configuring SwapOnZRAM]
** xref:sysconfig-configure-wireguard.adoc[Configuring WireGuard]
* Kernel Configuration
** xref:sysctl.adoc[Kernel Tuning]
** xref:kernel-args.adoc[Modifying Kernel Arguments]
** xref:debugging-kernel-crashes.adoc[Setting up kdump]
* Other Configuration
** xref:managing-files.adoc[Managing Files]
** xref:authentication.adoc[Configuring Users and Groups]
** xref:sysconfig-setting-keymap.adoc[Setting Keyboard Layout]
** xref:os-extensions.adoc[Adding OS extensions]
** xref:sysconfig-configure-swaponzram.adoc[Configuring SwapOnZRAM]
** xref:alternatives.adoc[Setting alternatives]
** xref:counting.adoc[Node counting]
** xref:time-zone.adoc[Configuring Time Zone]
** xref:grub-password.adoc[Setting a GRUB password]
** xref:counting.adoc[Node counting]
* Running Containers
** xref:running-containers.adoc[Running Containers]
* OS updates
** xref:update-streams.adoc[Update Streams]
** xref:auto-updates.adoc[Auto-Updates]
Expand Down
65 changes: 65 additions & 0 deletions modules/ROOT/pages/disk-layout.adoc
View file
Open in desktop
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. 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
Open in desktop
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. 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.