RTFM · Install

Install to hardware

Write a downloaded 0.2.1 QCOW2 image to a real disk, USB stick, or external drive and boot physical hardware. There is no dedicated installer image yet: convert the image to raw, write the bytes, boot the machine.

Before you start

You need the downloaded archive with a verified checksum, a target drive of at least 16 GiB, and a writer tool for your operating system. The 0.2.1 images are bootable minimal systems, not installers: writing the image is the install.

Download a 0.2.1 image and verify its checksum before converting anything.
Pick the image matching the machine firmware: UEFI images carry a 64 MiB ESP, BIOS images a 1 MiB BIOS boot area.
Back up everything on the target drive first.

Writing an image destroys every byte on the target device. Confirm the device name twice before every write command.

Step 0: convert QCOW2 to raw

The download is a Zstandard-compressed tar archive containing one QCOW2 file. Extract it, inspect it, then convert to raw. No raw images are published; convert locally.

Extract and inspect

tar --zstd -xf saphira-uefi-systemd-0.2.1.qcow2.tar.zst
qemu-img info saphira-uefi-systemd.qcow2

Extraction yields the QCOW2 file without the version suffix. Substitute the archive name of the variant you downloaded.

Convert to raw

qemu-img convert -f qcow2 -O raw -S 4k \
    saphira-uefi-systemd.qcow2 \
    saphira-uefi-systemd.raw

The raw file is exactly 17179869184 bytes (16 GiB). Confirm the size before writing: anything else means a truncated download or a failed conversion.

Confirm raw size

ls -l saphira-uefi-systemd.raw

Step 1: write the image to disk

Any tool that writes bytes verbatim to a block device works. Pick one for your operating system:

Image writer tools
Tool	System	Notes
dd	Linux, macOS	Preinstalled everywhere Unix-like. Exact, scriptable, unforgiving about device names.
physdiskwrite	Windows	Small command-line writer for physical disks. Run as Administrator.
Rufus	Windows	Choose DD mode when offered so the image lands verbatim.
balenaEtcher	Linux, macOS, Windows	Graphical, verifies the write afterwards.
USBImager	Linux, macOS, Windows	Minimal graphical writer with verification.

1. Identify the target, twice
Linux: lsblk -d -o NAME,SIZE,MODEL. macOS: diskutil list. Windows: check Disk Management. Unplug the drive, list again, replug, list again: the entry that appears is your target.
2. Unmount it
The writer needs the raw device. Linux: unmount any mounted partitions. macOS: diskutil unmountDisk /dev/diskN.
3. Write and sync
Run the write, wait for completion, then flush caches before unplugging: sync on Unix, eject or safely remove everywhere.

Write with dd on Linux

sudo dd if=saphira-uefi-systemd.raw of=/dev/sdX bs=4M conv=fsync status=progress
sync

Write with dd on macOS

diskutil unmountDisk /dev/diskN
sudo dd if=saphira-uefi-systemd.raw of=/dev/rdiskN bs=4m
sync

Replace /dev/sdX and /dev/rdiskN with your target from the identification step. On Windows, run physdiskwrite as Administrator and select the target disk number, or point Rufus, Etcher, or USBImager at the raw file and the target drive. There is no undo.

Optional verification: read the device back and compare, e.g. sudo cmp saphira-uefi-systemd.raw /dev/sdX. It takes as long as the write and proves the bytes landed.

Inspect the partitions first

Before you reboot hardware on the image, look at it on your build machine. fdisk lists the layout straight from the raw file or from the written drive; the shape below is what a healthy 0.2.1 image looks like.

List image and device partitions

fdisk -l saphira-uefi-systemd.raw
fdisk -l /dev/sdX

Disklabel type gpt on a 16 GiB disk, for every variant.
UEFI images: a 64 MiB EFI System partition followed by a Linux filesystem partition of about 8 GiB.
BIOS images: a 1 MiB BIOS boot area followed by a Linux filesystem partition of about 8 GiB.
Roughly 8 GiB with no partition after that: the spare space from Step 4.

If fdisk shows anything else, stop: the download truncated, the conversion failed, or the write went to the wrong device.

Mount, chroot, or boot it in a container

Mount the root partition and look inside before the hardware ever boots it. qemu-nbd exposes the QCOW2 partitions directly, so no conversion is needed for this check.

Expose and mount the root partition

sudo modprobe nbd
sudo qemu-nbd --connect=/dev/nbd0 saphira-uefi-systemd.qcow2
sudo mount /dev/nbd0p2 /mnt
ls /mnt

With the root mounted, either chroot into it or boot it as a lightweight container. Both stay on your build machine; neither touches the hardware.

Inspect with chroot

sudo mount --bind /dev /mnt/dev
sudo mount -t proc proc /mnt/proc
sudo mount -t sysfs sys /mnt/sys
sudo chroot /mnt /bin/sh

Inspect with systemd-nspawn

sudo systemd-nspawn -D /mnt /bin/sh

Inside, confirm the essentials: the kernel modules under /lib/modules, the installed package set, and the /boot contents. Then exit, unmount in reverse order, and disconnect the device.

Clean up

exit
sudo umount /mnt/dev /mnt/proc /mnt/sys /mnt
sudo qemu-nbd --disconnect /dev/nbd0

Prefer raw for loop mounting instead: sudo losetup -Pf saphira-uefi-systemd.raw exposes /dev/loop0p1 and /dev/loop0p2 the same way. systemd-nspawn needs a host running systemd and root in both cases.

Step 2: boot the machine

1. Attach the drive
Connect the USB stick or install the disk in the target machine.
2. Match the firmware mode
Enter the boot menu (often F12, F8, or Esc) and boot the drive in the mode matching your image: the UEFI entry for UEFI images, the legacy or BIOS entry for BIOS images. The wrong mode will not boot.
3. First boot
The machine boots into the minimal Saphira system. Log in on the console and look around before changing anything.

Prove it works: hardware boot

the machine reaches a Saphira login on the written drive, and the booted image matches the variant you wrote: firmware mode and init system.

Step 3: first checks on hardware

Confirm the machine is running what you wrote, then check the hardware-specific basics: storage without errors and working network.

Confirm kernel, init, and boot messages

uname -r
ps -p 1 -o comm=
dmesg | tail -30

uname -r reports the running kernel, ps shows the init system, and the tail of dmesg surfaces storage or firmware complaints while they are still easy to attribute.

Step 4: use the spare space

Each image partitions about 8 GiB and leaves about 8 GiB unallocated on the 16 GiB disk. That spare space is yours to grow into later with standard partitioning tools once the system runs the way you want.

A dedicated installer image that performs this setup for you is planned but not published yet. Until then, this convert-and-write path is the supported route to hardware.

Where next

Did we miss something?

If this page left something unanswered, found an error, or there is another subject you would like documented, tell us. Saphira’s documentation grows from real problems people need to solve.

Send feedback or request a new section →

Prefer not to do it yourself?

Everything needed to do the work yourself is documented here and remains free; we charge for human time, not for withholding knowledge. Sometimes the missing resource is simply time. The same people who build Saphira can provide paid professional help with implementation, migration, troubleshooting and administration.

Ask about professional support →