laantungir/n_os_tr
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
master
n_os_tr/plans/network_boot.md
Laan Tungir 6e2164abe5 [WARNING] No existing semantic tags found. Starting from v0.0.0 
v0.0.1 - Reorganize ISO build tree, add docs/plans/scripts, and stage Phase 2 Slice B+C service integration artifacts
2026-04-29 13:09:28 -04:00

16 KiB
Raw Permalink Blame History

Network Booting the n-os-tr ISO from the Internet

Status: Paused / On Hold

This document captures the design thinking, hardware validation, and implementation plan for letting a client machine boot the n-os-tr live ISO directly from a URL on the internet — no local installation media required.

Current state: feasibility fully validated on the target hardware. Server-side infrastructure not yet built. Resume here when ready.

1. The Goal

Make it possible to power on a bare-metal machine, press a key, and have it boot straight into a running n-os-tr live environment whose kernel, initrd, and root filesystem were downloaded over HTTPS from a server on the public internet at boot time. No USB stick, no local disk, no LAN-side boot infrastructure required.

This complements — rather than replaces — the ISO file we already produce in build.sh. The ISO remains the primary deliverable; network boot becomes a second distribution channel for that same set of artifacts.

2. Options Considered

Five distinct network-boot approaches were evaluated. They are listed in order of "how close to the goal of booting from an internet URL with nothing on the LAN".

Option 1: UEFI HTTP(S) Boot (firmware-native)

Modern UEFI 2.5+ firmware (≈2015 and newer) can itself fetch a .efi bootloader over HTTP/HTTPS from any URL. No PXE server, no TFTP, no USB stick. You enter the URL into the BIOS (or supply it via DHCP option 67) and the firmware does the rest.

  • Pros: zero LAN-side infrastructure, cleanest flow, one-time BIOS setup.
  • Cons: requires UEFI 2.5+ with the feature exposed; older BIOSes don't have it; many consumer BIOSes hide or restrict the option.
  • Selected as primary path for this project. See §4 for hardware validation.

Option 2: Classic PXE with iPXE chainload

BIOS uses its PXE Option ROM to DHCP on the LAN and TFTP-load a bootloader. That bootloader is iPXE, which then has full HTTPS support and fetches everything else from the internet.

  • Pros: works on essentially any BIOS from ~2005 onward. Well-documented.
  • Cons: requires a DHCP and TFTP server on the LAN. More infrastructure setup.
  • Secondary fallback if HTTP Boot ever becomes unavailable.

Option 3: iPXE on a USB stick (or CD)

Flash the ~1 MB ipxe.usb image to any USB drive and boot from USB. iPXE launches, reaches the internet over HTTPS, and fetches the ISO assets. Once the stick is made, it's effectively a permanent "network boot" key — the ISO lives on the internet and can be updated server-side without touching the stick.

  • Pros: works on any machine that can boot USB (i.e. all of them). Zero BIOS configuration needed. Zero LAN infrastructure needed.
  • Cons: requires distributing a physical medium one time per machine.
  • Universal fallback when neither HTTP Boot nor PXE are usable.

Option 4: netboot.xyz

Hosted iPXE menu service at netboot.xyz. Flash their USB or point PXE at their URL; get a menu of hundreds of bootable OSes. Can be extended with custom menu entries for your own ISO.

  • Pros: no build step needed; community-maintained.
  • Cons: dependency on third-party service; extra indirection for a single-ISO use case.
  • Not chosen. More value for general-purpose multi-distro booting than for a single project's distribution channel.

Option 5: GRUB with http + loopback modules

GRUB 2 can load .iso files over HTTP and loopback-mount them using the http and net modules. Requires GRUB already installed somewhere (local disk, USB, or chainloaded).

  • Pros: familiar bootloader; loopback-mount of real ISOs.
  • Cons: niche; less common tooling; redundant next to iPXE.
  • Not chosen.

3. Decision Tree

flowchart TD
    Start[Want to netboot ISO from the internet] --> Q1{UEFI HTTP Boot<br/>available?}
    Q1 -->|Yes| UEFI[Configure URL in BIOS<br/>firmware fetches .efi]
    Q1 -->|No| Q2{BIOS supports<br/>PXE?}
    Q2 -->|Yes| Q3{Can you run a<br/>LAN DHCP+TFTP server?}
    Q3 -->|Yes| PXE[Local DHCP+TFTP<br/>chainload iPXE to HTTPS]
    Q3 -->|No| USB1[iPXE USB stick]
    Q2 -->|No| USB2[iPXE USB stick]
    UEFI --> ISO[ISO served from HTTPS]
    PXE --> ISO
    USB1 --> ISO
    USB2 --> ISO

4. Hardware Validation (Target: ASRock B650I Lightning WiFi)

The target platform is the ASRock B650I Lightning WiFi motherboard (AMD AM5, Ryzen 7000 series CPUs, 2.5 GbE Realtek RTL8125BG, Wi-Fi 6E). Reference: B650I Lightning WiFi.pdf.

4.1 Firmware Facts

From the manual's Section 1.2 Specifications:

  • BIOS family: AMI Aptio V UEFI ("AMI UEFI Legal BIOS with GUI support", p. 5)
  • Onboard LAN: Dragon RTL8125BG 2.5 GbE (p. 3)
  • Wi-Fi: 802.11ax Wi-Fi 6E module (p. 3)
  • BIOS Flashback button: present (Section 2.13, pp. 47–48) — allows BIOS update with no CPU, RAM, or GPU installed.

4.2 BIOS Revision Tested

  • Current BIOS on the unit: version 3.01 (released 2024-05-14, AGESA 1.1.7.0)
  • Latest stable at time of writing: 4.10 (2026-03-03, AGESA 1.3.0.0a)
  • None of the release notes between 1.28 (initial) and 4.10 mention Network Stack / HTTP Boot / PXE changes — the feature set for UEFI networking has been stable across all revisions. Updating is therefore not expected to add or remove HTTP Boot capability.

4.3 CSM (Legacy BIOS Compatibility)

  • CSM cannot be persistently enabled on this board. Every attempt resets to disabled on reboot. This is normal and expected on AM5 — AMD removed legacy Option ROM support at the silicon level in Ryzen 7000, so CSM is a vestigial menu item only. The platform is UEFI-only by design.
  • This is the correct state for UEFI HTTP Boot; no action required.

4.4 BIOS Menu Layout Discovered

The Network Stack menu layout on this specific BIOS revision is partial:

  • ✅ Advanced → IPv4 Network Configuration (exposed)
  • ✅ Advanced → IPv6 Network Configuration (exposed)
  • ❌ Parent "Network Stack" toggle with Ipv4 PXE Support / Ipv4 HTTP Support sub-options — not visible in the UI on BIOS 3.01.
  • ✅ However, the Advanced → Onboard Devices Configuration submenu does exist on this board (confirmed by the warning text on ASRock's BIOS download page referencing BIOS\Advanced\Onboard Devices Configuration\Display Priority). Typical options there: Change LEDs, Display Priority, HD Audio, Onboard LAN, WAN, Bluetooth toggles — but no Network Stack option inside on 3.01.

4.5 HTTP Boot Status: ENABLED AND ACTIVE

Empirical probe via the F11 one-shot boot menu revealed two UEFI network boot entries already present:

UEFI: PXE IPv4 Realtek PCIe GbE Family Controller
UEFI: HTTP IPv4 Realtek PCIe GbE Family Controller   ← this one, confirmed present

On this BIOS revision ASRock ships Network Stack auto-enabled with both PXE and HTTP IPv4 supported, even though the granular toggle for HTTP Support is not surfaced in the Setup UI. No BIOS configuration change is required to use HTTP Boot on this machine.

4.6 Wi-Fi Boot

  • Not supported. The Wi-Fi 6E module is not exposed to the UEFI network stack. Network boot requires wired Ethernet plugged in at POST time. Once the live system is running, Wi-Fi works normally (via Linux drivers, not firmware).

4.7 Summary Table

Capability Status on this board with BIOS 3.01
UEFI HTTP Boot (IPv4) ✅ Active and ready
UEFI HTTPS Boot ⚠️ Likely requires certificate enrollment; not investigated
UEFI PXE (IPv4) ✅ Active
Legacy CSM/PXE ❌ Not possible on AM5 platform
Wi-Fi boot ❌ Not supported by firmware
BIOS Flashback for recovery/upgrade ✅ Available (no CPU/RAM/GPU required)

Bottom line: the hardware is ideal for this use case. Zero firmware work is needed; the only remaining task is building the server-side delivery chain.

5. Target Architecture

flowchart TD
    subgraph Client [Client machine B650I or compatible]
        A[Power on → F11 boot menu]
        A2[Select UEFI HTTP IPv4]
    end
    subgraph Server [Public HTTPS server host TBD]
        B[bootx64.efi<br/>~1MB iPXE UEFI binary<br/>with embedded script]
        C[boot.ipxe<br/>boot script]
        D[vmlinuz<br/>Linux kernel]
        E[initrd.img<br/>Debian live initramfs]
        F[filesystem.squashfs<br/>compressed root FS]
    end
    A --> A2
    A2 -->|1. HTTP GET bootx64.efi| B
    B -->|2. firmware launches iPXE| IPXE[iPXE running]
    IPXE -->|3. HTTPS GET boot.ipxe| C
    C -->|4. HTTPS GET kernel and initrd| D
    C --> E
    E -->|5. initramfs HTTPS GET fetch=squashfs| F
    F --> Live[n-os-tr live system running]

Protocol Notes

  • Step 1 (firmware → bootx64.efi): plain HTTP. UEFI 2.5+ firmware generally supports HTTPS boot only with CA certificates enrolled into the firmware trust store — extra complexity, and on ASRock consumer boards this path is not well-documented. Plain HTTP is acceptable for this one hop because:
    1. The binary is ≤ 1 MB and trivial to re-serve.
    2. iPXE binaries can be code-signed separately and/or hash-verified.
    3. All subsequent traffic is HTTPS.
  • Steps 3–5 (iPXE and live-boot): HTTPS. iPXE has modern TLS support and live-boot uses standard libcurl/wget semantics via the fetch=URL kernel parameter. No special configuration required to use HTTPS throughout.

Artifact Inventory

File Size Source Hosted at (example)
bootx64.efi ~1 MB Built from iPXE with embedded script http://boot.example/bootx64.efi
boot.ipxe ~1 KB Hand-written https://boot.example/n-os-tr/boot.ipxe
vmlinuz ~8–15 MB live-build output at binary/live/vmlinuz https://boot.example/n-os-tr/vmlinuz
initrd.img ~30–50 MB live-build output at binary/live/initrd.img https://boot.example/n-os-tr/initrd.img
filesystem.squashfs ~1–2 GB live-build output at binary/live/filesystem.squashfs https://boot.example/n-os-tr/filesystem.squashfs

6. Implementation Plan (When Resumed)

Phase 1: Proof-of-Concept — Build iPXE

  • Clone github.com/ipxe/ipxe.
  • Create an embedded script myscript.ipxe that DHCPs and chainloads https://boot.example/n-os-tr/boot.ipxe.
  • Enable in src/config/general.h:
    • DOWNLOAD_PROTO_HTTPS
    • NET_PROTO_IPV6 (optional but recommended)
  • Build: make bin-x86_64-efi/ipxe.efi EMBED=myscript.ipxe.
  • Upload resulting .efi to the webserver as bootx64.efi.

Phase 2: Choose and Configure the Hosting

  • Decide where to host:
    • Plain nginx/Apache on a VPS.
    • The project's own includes/ginxsom/ Blossom server — natural fit for the static squashfs given content-addressing.
    • An object store (S3 / R2 / Backblaze) fronted by a CDN.
  • Ensure the host serves .efi with an appropriate MIME type (application/octet-stream or application/efi).
  • Verify HTTP (not HTTPS) works for the bootx64.efi endpoint — some hosts redirect HTTP→HTTPS by default and the UEFI firmware may not follow redirects.

Phase 3: Extend build.sh to Publish Artifacts

  • After lb build completes, copy binary/live/vmlinuz, initrd.img, and filesystem.squashfs out of the build tree.
  • Push them to a versioned path on the webserver (e.g. /n-os-tr/v${VERSION}/...).
  • Update a /n-os-tr/latest/ symlink or alias.
  • Regenerate boot.ipxe to reference the correct versioned paths.
  • Consider integrity: publish a SHA-256 manifest alongside the artifacts so iPXE's imgverify / manual verification can catch tampering even over plain HTTP.

Phase 4: Write boot.ipxe

#!ipxe
set base-url https://boot.example/n-os-tr/latest

echo Loading n-os-tr from ${base-url}
kernel ${base-url}/vmlinuz boot=live components quiet splash \
       fetch=${base-url}/filesystem.squashfs
initrd ${base-url}/initrd.img
boot

Phase 5: Optional — DHCP Option 67 for Hands-Free Boot

If the LAN's DHCP server is controllable, set DHCP option 67 (Boot-File-Name) so the client firmware auto-receives the URL instead of prompting at boot.

  • ISC dhcpd: 
    option arch code 93 = unsigned integer 16;
class "httpclients" {
    match if substring (option vendor-class-identifier, 0, 10) = "HTTPClient";
    option vendor-class-identifier "HTTPClient";
    if option arch = 00:10 {
        filename "http://boot.example/bootx64.efi";
    }
}
  • dnsmasq: 
    dhcp-vendorclass=set:httpboot,HTTPClient
dhcp-boot=tag:httpboot,http://boot.example/bootx64.efi
  • Result: F11 → HTTP IPv4 → boots with zero user input.

Phase 6: End-to-End Test

  • Fresh boot of the B650I target with wired Ethernet connected.
  • F11 → UEFI: HTTP IPv4 Realtek … → enter (or auto-receive) URL.
  • Confirm iPXE banner appears.
  • Confirm boot.ipxe is fetched and executed.
  • Confirm kernel + initrd load.
  • Confirm squashfs streams in and live system boots to login prompt.
  • Confirm n-os-tr-firstboot and n-os-tr-smoketest behave identically to the USB-boot case.

7. Open Questions for When We Resume

  1. Where are we hosting the artifacts? Public VPS with nginx, project-owned ginxsom/Blossom, object store + CDN, or something else?
  2. Versioning strategy: /latest/ symlink, or require client to supply a version in the URL? Rollback semantics?
  3. HTTPS Boot (instead of plain HTTP) for the first hop: worth the certificate-enrollment effort, or is integrity via out-of-band hash pinning enough?
  4. Signed iPXE: do we want to build a Secure Boot-signed iPXE so that Secure Boot can remain enabled on clients? Shim + MOK, or use an existing signed build?
  5. Multi-arch: is arm64 (aarch64) netboot ever in scope, or x86_64 only? (If yes, second iPXE build for bin-arm64-efi/ipxe.efi.)
  6. Observability: do we want a log/telemetry endpoint so that network- booted clients phone home on successful boot?
  7. Fallback distribution: still ship the full .iso for USB installs? (Answer assumed "yes" — network boot is additive, not a replacement.)

8. Known Limitations

  • Wired Ethernet required at boot time. No Wi-Fi netboot on consumer UEFI.
  • Plain HTTP for the bootloader hop unless certificate enrollment is done; mitigate with hash verification.
  • Boot speed bounded by internet throughput for the ~1–2 GB squashfs. A cached/CDN-fronted origin is strongly recommended for realistic fleet use.
  • No offline fallback by design — this is complementary to the regular USB ISO, not a replacement.
  • BIOS 3.01 on the target doesn't expose a UI toggle for Ipv4 HTTP Support but the feature is active by default. If a future BIOS revision changes this, revisit via F11 inspection as in §4.5.

9. References