Boot stick and boot loader

FAQ › EUZOS Desktop › Boot stick and boot loader · Nederlands

What is it?

EUZOS starts from a FAT32 volume with a fixed layout: a UEFI boot loader of its own (\EFI\BOOT\BOOTX64.EFI on x86-64, BOOTAA64.EFI on ARM64) that loads the kernel (\EOS\KX64.ELF, or \EOS\KAA64.ELF on ARM64) plus all files in \EOS\FW\ (firmware and settings) into memory, and jumps to it. That volume is a USB stick (made with make image) or, after an installation, the EFI system partition (ESP) of the internal disk. The kernel calls whichever one it booted from the boot volume; the console commands still say stick for both.

When EUZOS starts from a USB stick, a choice screen comes first: Try EUZOS or Install on this PC. Holding I while switching on skips the choice and goes straight to the installer. A trial kernel can be started once (try) and then made permanent (commit).

How do I…?

How do I make an EUZOS stick?

On the development Mac: make image (EUZOS Desktop, test build) writes the image with the boot loader, kernel, programs, firmware and a signed release manifest (\EOS\MANIFEST.TXT + \EOS\MANIFEST.SIG). Without that signed manifest the stick still boots, but cannot install (the choice screen says so). See docs/INSTALLING.md, "Where the files come from". A running EUZOS can also write a new stick from a release on the network: install <url> <disk> (see Installer).

What do I see when the stick boots?

1. The boot loader prints lines starting with [EUZOS-boot] (display mode, ACPI, which kernel it loaded) and draws coloured bars at the top.
2. The kernel shows the boot screen: the EUZOS logo with a calm animation and a status line. Esc shows the boot text; Esc again (or another key) returns to the boot screen. An error line or a panic shows the text at once.
3. Booted from a USB stick (x86-64 only): the choice screen "Welcome to EUZOS" with Try EUZOS ("From the stick; nothing on this PC changes") and Install on this PC ("On the internal drive; everything on it will be erased"). After 10 seconds without a choice it becomes Try; a tap, click or arrow key stops the countdown.
4. Try continues to the normal login screen.

How do I go straight to the installer (the I key)?

Hold I (or i) while switching on. The boot loader does not wait for it: it only looks at what is already in the firmware's keyboard buffer (at most 64 keys) just before leaving the firmware. If there is an I, it passes the flag BOOT_INSTALL to the kernel, which skips the choice screen and opens the installer at the disk step. Without I the boot is just as fast as before.

Why is the choice screen in the kernel and not in the boot loader?

It must work with a finger (the Panasonic CF-33 and FZ-G1 tablets only have a touchscreen, and their UEFI has no touch), it must be graphical in all languages and both themes, and it needs the on-screen keyboard. All of that exists only in the kernel. The boot loader only passes on the I key.

How do I switch the choice screen off?

Put choice=no (legacy keuze=nee) in \EOS\FW\INSTALL.TXT on the stick (for example a test stick that must always continue booting). The screen also does not appear when booting from the internal disk, on ARM64, or on an installation stick (automatic=yes, legacy automatisch=ja, see Installer).

Since 27-10-2026 EUZOS writes English config file names, keys, values and confirmation words (for example WIPE-…, environment= in PROFILE.TXT); the old Dutch names (marked legacy here) are still read and accepted (docs/ENGLISH.md).

Why does my PC boot the stick even though EUZOS is installed on the SSD?

After an installation the internal disk is first in the UEFI BootOrder, so the firmware boots the SSD even with a stick plugged in. The boot loader on the internal disk therefore looks for an EUZOS stick on USB (it must have \EFI\BOOT\BOOTX64.EFI, \EOS\KX64.ELF and \EOS\MANIFEST.TXT); if it finds one, it starts the stick's boot loader (LoadImage/StartImage), and the stick boots as if the firmware had chosen it. Switch this off with stick=no (legacy value stick=nee) in \EOS\FW\BOOT.TXT on the internal disk (legacy name OPSTART.TXT, still read).

How do I see which volume EUZOS booted from?

stick lists the USB storage devices, then the boot volume (USB stick or internal SATA/NVMe disk), its sector and cluster size, how it was chosen (the boot partition GUID from the boot loader, or the label EUZOS with an old boot loader), and the sizes of EOS/KX64.ELF, EOS/KX64TRY.ELF and EOS/TRY.TXT.

How do I test a new kernel without risk?

1. Put the new kernel on the boot volume as \EOS\KX64TRY.ELF (over SSH: ssh euzos 'put EOS/KX64TRY.ELF' < kernel; the Mac script tools/trial.sh builds, uploads and does the rest).
2. try: writes the marker \EOS\TRY.TXT and reboots.
3. The boot loader sees TRY.TXT, deletes it first, and boots the trial kernel once. If that kernel hangs or crashes, the next boot takes the committed kernel again.
4. If the trial kernel works: commit (run from the trial kernel).

A trial kernel that panics, faults, or has a lock stuck for 20 seconds writes a report to \EOS\HANG.TXT and reboots by itself into the committed kernel; the next kernel puts HANG.TXT in its log and deletes it.

What does commit check?

That KX64TRY.ELF is a valid kernel for this machine (ELF64, little-endian, position-independent, right architecture, at least 64 KiB), and, for a build with a build ID other than dev, that the trial kernel is the kernel running now. Then it copies the current KX64.ELF to KX64OLD.ELF, writes the trial kernel over KX64.ELF and reads it back.

What if the committed kernel does not load?

The boot loader tries kernels in order: (the trial kernel, once, if TRY.TXT was there) → KX64.ELF → KX64OLD.ELF (the backup made by commit). The first one that reads and loads wins; a broken file gives a message, not a crash. If none loads: "no usable kernel on the stick".

How do I put a file on the boot volume or delete one?

• fetch <url> <path>: fetch over HTTPS and write only if <url>.sig is a valid signature with the key in \EOS\FW\SIGNPUB.TXT, and the version is not older than the one remembered in \EOS\FW\FETCH.TXT (anti-rollback; the legacy HAAL.TXT is still read, and per name the highest version of the two counts).
• Over SSH: put <path> with the data on stdin; this checks only the path rule below, not a signature (see Console).
• stick wipe <path> removes a file.

Writing is only allowed inside \EOS\ and never directly to the committed kernels KX64.ELF/KAA64.ELF (only commit replaces those); \EFI\ is never touched, so the stick always keeps booting.

How do I diagnose a PC that hangs while booting?

Put \EOS\FW\BOOTDIAG.TXT on the stick (an empty file is fine). The boot loader then draws a column of coloured blocks per step, can try other ways of leaving the firmware (ebs=), pause before the jump (pause=) and reboot after N seconds as a sign of life (reboot=). Take photos of the screen. See docs/BOOT-DIAGNOSTICS.md.

How do I always get the console instead of the boot and login screen?

Put console in \EOS\FW\SCREEN.TXT. Then there is no boot screen and no login screen (see Console).

Details

Boot loader steps

From boot/src/main.rs:

1. Read \EOS\FW\BOOTDIAG.TXT first (diagnostic mode).
2. Create the UEFI boot entry for a freshly installed internal disk if the marker \EOS\FW\UEFIBOOT.TXT is there (by default as the very first step).
3. Query the framebuffer (GOP); change the display mode only if the current one is unusable or a really larger one exists (up to 1920x1200).
4. Find the ACPI RSDP and device tree pointers.
5. TRY.TXT: remove it, and if a trial kernel exists, boot it once.
6. Load every file in \EOS\FW\ (no subdirectories) into memory; a missing directory is fine. Limits: 64 files, 32 MiB per file, 256 MiB in total (see Files from \EOS\FW\).
7. Copy the SMBIOS table (the device model, for DriverEnricher).
8. Load the kernel ELF (trial → committed → backup).
9. Read the I key from the keyboard buffer.
10. Get the memory map, ExitBootServices, and jump to the kernel with a BootInfo (flags, kernel name, boot partition GUID, files, framebuffer).

The boot entry after an installation

The installer writes \EOS\FW\UEFIBOOT.TXT with the partition GUID on the new ESP. On every boot the boot loader checks internal disks (SATA or NVMe in the device path, never USB) for that file. If the GUID matches, it reuses or creates a Boot#### entry for \EFI\BOOT\BOOTX64.EFI on that partition, puts it first in BootOrder, reads BootOrder back and only then deletes the marker. If anything fails, the marker stays and the next boot tries again.

Boot flags passed to the kernel

Files from \EOS\FW\

The boot loader passes at most 64 files of at most 32 MiB each and 256 MiB in total (libs/bootinfo: MAX_FILES, MAX_FILE_SIZE, MAX_FILES_TOTAL); until 27-10-2026 it was 16 files of 16 MiB, and files beyond that dropped out silently. Now a skipped file (too many, too large, total full, unreadable, or a name that is not 8.3 ASCII) gets a line [EUZOS-boot] SKIPPED firmware file <name> ... on the boot loader's screen, and the kernel prints WARNING : the bootloader skipped N file(s) from \EOS\FW\. Config files that are missing from the list (SSHD, AUTHKEYS, HOSTKEY, PCKEY, LANG, NETWORK, FIREWALL, WORKPLC) are then read from the boot volume instead (settings_file::boot_file_or_volume).

Old and new mixed (the BootInfo layout is append-only; the version stays 6 and the extension is announced with the flag BOOT_FILES_EXT):

Choosing the right stick

With several sticks plugged in, the kernel opens the partition whose GPT GUID the boot loader reported. An internal disk is only ever used as boot volume via that GUID; the driver's lock then allows writes only within that partition, never the GPT or the rest of the disk.

Reference

Console commands

Legacy alias: haal = fetch.

Functions and modules

Config files

All in \EOS\FW\ on the boot volume unless noted.

Since 27-10-2026 EUZOS writes English config file names, keys, values and confirmation words (for example WIPE-…, environment= in PROFILE.TXT); the old Dutch names (marked legacy here) are still read and accepted (docs/ENGLISH.md).

Files on the boot volume

Protocol messages and formats

• Signature file <name>.sig (72 bytes): 8-byte version (Unix time of signing) + Ed25519 signature over the file name, the version and the content (euzos_crypto::ed25519::download_message).
• Fetch retries: after a network error up to three attempts per file (2 s, then 5 s pause), each with its own TLS connection; never after a refusal (signature, SHA-256, size, version, 404).
• Boot loader log: lines starting with [EUZOS-boot] on the screen and the serial port.

See also

• Installer · Login · Console · Updates
• docs/INSTALLING.md
• docs/BOOT-DIAGNOSTICS.md
• docs/UPDATES.md ("What already exists")
• docs/MILESTONE7.md