02 Finding the OS

The Problem

After firmware initializes the hardware (01 Power and Firmware), it needs to find an operating system. This sounds trivial -- "load a file from disk" -- but it's actually three distinct problems:

Where is the OS? On a local disk? On the network? On a USB stick?
Which OS? If multiple are installed, which one boots?
The bootstrap problem: How does the OS get onto the machine in the first place? The first-ever boot has no local OS to find.

The first two problems are solved by UEFI boot entries and the EFI System Partition. The third -- bootstrapping -- is where things get interesting, because different deployment scenarios (bare metal, VPS, development VM) need different answers.

How Boot Targets Work

The EFI System Partition (ESP)

The ESP is a small FAT32 partition (typically 100 MB to 1 GB) on the system's primary disk. It has a specific GPT partition type that firmware recognizes automatically. This is where bootloaders live.

Each OS installs its bootloader into its own subdirectory:

ESP/
  EFI/
    BOOT/
      BOOTx64.EFI          # Fallback (removable media, recovery)
    ubuntu/
      shimx64.efi          # Ubuntu's Secure Boot shim
      grubx64.efi          # Ubuntu's GRUB
    Microsoft/
      Boot/
        bootmgfw.efi       # Windows Boot Manager
    FortrOS/
      preboot.efi          # FortrOS preboot UKI

FAT32 is used because the UEFI spec requires all implementations to support it -- no OS-specific filesystem drivers needed. Every UEFI firmware on the planet can read FAT32.

Boot Entries (NVRAM)

The firmware maintains a boot priority list in NVRAM (non-volatile memory on the motherboard). Each entry has a label, a pointer to a file on the ESP, and an active/inactive flag. The BootOrder variable lists entries by priority.

On Linux, efibootmgr reads and writes these entries:

BootOrder: 0001,0003,0002
Boot0001* FortrOS    EFI/FortrOS/preboot.efi
Boot0002* ubuntu     EFI/ubuntu/shimx64.efi
Boot0003* Windows    EFI/Microsoft/Boot/bootmgfw.efi

Firmware tries each entry in order. If one fails (file missing, signature invalid), it tries the next. If all entries fail, it tries the fallback path \EFI\BOOT\BOOTx64.EFI on any ESP it finds. This fallback is how USB installers work without prior NVRAM configuration -- the firmware just finds the well-known filename.

NVRAM entries survive disk reformatting (they're on the motherboard, not the disk), but they point to files on the ESP. If the ESP is wiped, the entries still exist but point to nothing -- firmware skips them and drops to the setup screen.

Boot Methods

Method	How It Works	When It's Used
Local disk	Firmware reads ESP, loads bootloader	Normal boot (most common)
PXE	Firmware queries network for boot server via DHCP, downloads bootloader via TFTP	Data centers, provisioning, recovery
USB	Firmware finds ESP on USB device, loads fallback bootloader	Installation, rescue
HTTP Boot	Firmware fetches bootloader via HTTP/HTTPS (UEFI 2.5+)	Modern network provisioning
Cloud-init	VPS provider writes disk image before first boot	Cloud/VPS deployment

Network Boot (PXE)

PXE (Preboot eXecution Environment, pronounced "pixie") lets a computer boot from the network instead of a local disk. This is how data centers provision hundreds of machines without touching each one.

The sequence:

DHCP: The NIC's built-in PXE firmware broadcasts a DHCP request with PXE-specific options. A PXE-enabled DHCP server responds with an IP address plus the address of a TFTP server and the filename of a boot program.
TFTP: The NIC downloads the Network Bootstrap Program (NBP) from the TFTP server into RAM.
NBP runs: The NBP typically downloads a kernel and initramfs via TFTP, then hands off to the kernel.

PXE is deliberately minimal -- it only supports TFTP (a simple, slow, UDP-based file transfer protocol from 1981). This is a feature, not a bug: PXE needs to work on every NIC with a tiny firmware, so the protocol is as simple as possible.

iPXE is an open-source replacement that adds HTTP, HTTPS, DNS, scripting, and menu-based boot selection. It can be chainloaded from stock PXE firmware (PXE loads iPXE via TFTP, then iPXE takes over with richer protocols) or flashed directly onto the NIC.

UEFI HTTP Boot (spec version 2.5, 2015) is the modern alternative: firmware fetches the bootloader directly over HTTP/HTTPS using TCP. Much faster than TFTP (TCP windowing vs. TFTP's stop-and-wait), works across the internet (not just LAN), and supports TLS for secure transport.

Unified Kernel Images (UKI)

A UKI is a single file that bundles everything needed to boot into one UEFI executable. Traditional Linux boot uses separate files:

Traditional:                  UKI:
  /boot/vmlinuz-6.19           /boot/EFI/FortrOS/preboot.efi
  /boot/initramfs-6.19.img       (contains everything below)
  /boot/grub/grub.cfg             |- kernel
                                   |- initramfs
                                   |- command line
                                   |- OS metadata

The UKI format wraps these into a PE/COFF executable (the native format for UEFI) with named sections:

Section	Contents
`.linux`	The Linux kernel
`.initrd`	Initial ramdisk (initramfs)
`.cmdline`	Kernel command-line parameters
`.osrel`	OS identification
`.ucode`	CPU microcode updates
`.pcrsig`	TPM PCR signature policy

The critical advantage: everything is signed as one unit. With separate files, you sign the kernel and initramfs independently, and the command line lives in an unsigned config file (an attacker could add init=/bin/sh to get a root shell). With a UKI, the command line is inside the signed binary. You cannot tamper with any component without breaking the signature.

The UKI contains a small UEFI boot stub as its entry point. FortrOS uses ruki-stub -- a Rust UEFI application that reads the kernel, initramfs, and command line from the PE sections and hands control to the kernel via the Linux EFI boot protocol.

The Bootstrap Problem

Here's the chicken-and-egg: FortrOS boots from a UKI on the local ESP. But how does the UKI get onto the ESP in the first place? The machine has never seen FortrOS before. There's no local OS to download it.

Different deployment scenarios need different bootstrap paths:

Bare Metal: PXE or USB

A new physical machine has an empty disk. The bootstrap path:

Machine PXE boots from an existing FortrOS node acting as a PXE server
The PXE server delivers a minimal bootstrap image
The bootstrap image connects to the org over TLS
Downloads the real preboot UKI
Writes it to the local ESP
Reboots -- now the machine has a local preboot and never needs PXE again

PXE is the provisioning mechanism, not the ongoing boot mechanism. After bootstrap, the machine boots from local disk every time.

USB is the alternative when PXE isn't available: a bootstrap USB stick contains the same minimal image that would be PXE-served.

VPS: Out-of-Band Image Delivery

A VPS has no PXE and no USB. The bootstrap happens outside the VM:

The VPS provider's control plane writes a FortrOS disk image to the VM's virtual disk (via API upload, rescue mode, or custom ISO)
The image includes a preboot UKI on its ESP
The VM boots from its virtual disk -- it already has the preboot
The preboot connects to the org over TLS and completes enrollment

The VM's own OS never participates in its provisioning -- the image is delivered "out of band" by the hypervisor/management layer. Cloud-init can provide initial configuration (hostname, SSH keys, org gateway address) via the provider's metadata service or a NoCloud data source.

Development: QEMU/OVMF Direct Load

In the FortrOS QEMU development environment, OVMF (the UEFI firmware for VMs) loads the preboot UKI directly. No PXE, no USB, no image writing. This is a development convenience -- the scripts create a virtual ESP disk with the preboot UKI pre-installed.

The Common Path

All three bootstrap methods converge on the same result: a preboot UKI on the local ESP, with the org's CA public key and gateway address embedded in it. From this point forward, every boot follows the same path regardless of how the machine was initially provisioned.

How Others Do It

Talos Linux: Multiple Bootstrap, Same Outcome

Talos offers ISO, PXE, and pre-built disk images. PXE serves the Talos kernel and initramfs; ISO is burned to USB. Both boot into "maintenance mode" -- the node sits idle waiting for a machine config to be applied via Talos's API (or fetched automatically from a URL in the kernel command line). Once configured, Talos installs itself to disk. Disk images skip the install step entirely.

All paths converge: after first boot, every subsequent boot is from local disk with a UKI.

Similarity to FortrOS: Same convergent pattern. Multiple bootstrap paths, one steady-state boot path.

Flatcar / Fedora CoreOS: Ignition

These use Ignition -- a first-boot-only provisioning system. Boot from any medium (ISO, PXE, disk image). On first boot, Ignition reads a JSON config (from the cloud provider's metadata service, a URL, or local file) and executes it: partition disks, create filesystems, write files, configure services. Ignition is atomic -- if any step fails, the entire boot fails rather than producing a half-configured system.

Key difference from FortrOS: Ignition runs on the node itself during first boot. FortrOS's preboot connects to the org and gets provisioned remotely -- the configuration isn't provided at the bare-metal level, it's pulled from the cluster.

NixOS: Conventional Installer

NixOS uses a traditional approach: boot from an ISO, manually partition disks, write a declarative configuration file, run nixos-install. The entire system is built from the Nix store before the first real boot. Subsequent changes are declarative rebuilds.

Key difference from FortrOS: NixOS requires a human (or script) to run an installer. FortrOS is self-provisioning -- the bootstrap image handles everything automatically once it can reach the org.

The Tradeoffs

Dimension	PXE bootstrap	USB bootstrap	Pre-built image	Installer
Human involvement	None (if PXE server exists)	Physical access needed	Provider API	Human runs installer
Network required	Yes (LAN)	No (for bootstrap)	No (for bootstrap)	Optional
Works remotely	Yes	No	Yes (VPS API)	No
First-boot speed	Fast (small download)	Fast (local media)	Instant (already on disk)	Slow (full install)
Complexity	Need PXE server	Need USB creation	Need image pipeline	Need installer

FortrOS targets zero-touch provisioning: new hardware PXE boots from the org and provisions itself. USB provides a bootstrap medium when PXE isn't available. VPS providers deliver pre-built disk images out-of-band (the provisioning medium is the provider's API, not PXE or USB).

How FortrOS Does It

FortrOS uses a preboot UKI as the universal boot entry point. Every boot -- cold start, reboot, recovery -- goes through the same preboot code path.

The preboot UKI is org-scoped: it's the same binary for every node in the org. It contains the org's CA public key and gateway address baked into its initramfs. Per-node differentiation happens at runtime (TLS authentication with the gateway), not at build time.

The bootstrap path installs this UKI to the ESP once. After that:

Every boot:
  Firmware loads preboot UKI from ESP
    -> Preboot runs (next chapters cover what it does)
    -> Connects to org, authenticates, gets key material
    -> Unlocks /persist, selects kernel generation
    -> kexec into the real OS

PXE exists for two purposes after bootstrap:

Recovery (controlled LAN only): If the ESP is corrupted, a node can PXE boot from another org node on the same LAN to re-provision. This requires controlled DHCP -- the org must own the network segment. On untrusted networks, a rogue DHCP server could serve a malicious image. UEFI HTTP Boot over TLS is the future recovery path for untrusted environments (the firmware verifies the server's TLS certificate before downloading).
Data center cold boot: In racks where machines PXE from each other (controlled L2 network by definition)

Why This Follows From FortrOS's Principles

Immutable base (principle 1): The preboot UKI is a signed, read-only binary on the ESP. It doesn't change between boots. Updates replace it atomically via rolling upgrade.
Level-triggered (principle 2): The preboot doesn't care how it got there. Every boot is the same: check for hibernate image, check for cached generation, connect to org. No "first boot" vs "subsequent boot" branching.
Self-organization (principle 9): New hardware PXE boots, provisions itself, and joins the org without manual intervention.

Stage Boundary

What This Stage Produces

After firmware finds and loads the boot target:

The preboot UKI is loaded into memory from the local ESP
If Secure Boot is enabled, the UKI's signature has been verified
The UKI's embedded command line will be used (cannot be tampered with)
ruki-stub has measured UKI sections into TPM PCRs

On first-ever boot (bootstrap), the UKI isn't on the ESP yet. The bootstrap image (PXE, USB, or pre-built disk image) downloads the real preboot UKI, writes it to the ESP, and reboots. The machine never boots directly from what it received over the network -- it always writes to ESP first, then boots from ESP. After the reboot, the normal path below applies.

What Happens Next

The preboot UKI is running. It handles trust establishment (03 Trust and Identity), disk encryption (04 Disk Encryption), and loading the real OS (05 Loading the Real OS).

What This Stage Does NOT Do

It does not decide which kernel version to boot (that's the preboot's job)
It does not unlock encrypted storage (that's the preboot's job)
It does not contact the org (that's the preboot's job)
It does not configure networking beyond what PXE/DHCP provides for bootstrap