Skip to content

RTFM · Image Creator

Install to disk: real disks, readable rules.

Install-to-disk runs the image engine onto a whole physical disk: the same partition generator, the same installer and identity replay, the same init preparation, the same PARTUUID-stable bootloader. Only the backing differs from an image build, and the safety rules are absolute.

← Image Creator
Saphira Linux dragon mascot

When it refuses, and why

The refusal list is not red tape; each line exists because the alternative is exactly how disks get lost. install-to-disk refuses outright, without prompting, when:

  • the target is installer media: usb-installer is refused because the installer environment is an image, never an installed system.
  • the device argument is a partition instead of a whole disk: a partition is never a target because the tool owns the whole table. Pass /dev/sda, not /dev/sda1.
  • the device does not exist, is not a block device, has any mounted partition or active swap, or hosts the running system.
  • the typed confirmation does not match the device path; until it does, nothing at all is touched.

The safety model

Installing wipes the whole disk, so the tool is built to make accidents structurally impossible rather than merely unlikely:

  • No default device, no discovery, no --yes: the --device path is mandatory on every run.
  • The complete plan is always printed first; --preview prints it and stops without touching the device.
  • A real run requires the operator to type the device path back before anything is partitioned: confirmation of destruction, not a checkbox.
  • A device is refused outright when it does not exist, is not a block device, is a partition rather than a whole disk, has any mounted partition or active swap, or hosts the running system.
  • Before partitioning, every existing signature on the disk (partition tables, filesystem superblocks, RAID and LVM metadata) is wiped, and only after the typed confirmation and only on the confirmed device.
  • On failure the disk is unmounted and left as-is for diagnosis; nothing is wiped by the error path.

Never install to an unverified system disk. Confirm the device path independently (for example by size and model), run with --preview first, and type the path back only when you are certain. There is no undo.

The tool's own help states the model in six lines, and they are worth reading in the tool's own words:

  install-to-disk NEVER guesses a device: there is no default, no
  discovery and no --yes. The plan is always printed first and the
  operator must type the device path back to confirm destruction of
  everything on it. A device is refused outright when it does not
  exist, is not a block device, has any mounted partition or active
  swap, or hosts the running system. Preview mode touches nothing.
sudo saphira-image install-to-disk --preview \
  --target uefi-saphirad --device /dev/sda

sudo saphira-image install-to-disk \
  --target uefi-saphirad --device /dev/sda --allocate 128G

What you pass, and what it costs

Every install-to-disk run is two commands long, on purpose:

  • First, --preview: the complete plan is printed and nothing at all is touched. Checking a plan costs nothing; guessing about a device costs a disk.
  • Then the real run: the complete plan is always printed on real runs too, and the typed device path is the commit point. There is no --yes, no --force and no undo past it.
  • Disk growth is kept, not spent: --allocate partitions only the stated share (absolute size or percentage) and the remainder stays unallocated for later growth. ESP capacity and root size behave exactly as they do in build, same refusals and same alignment.
  • Identity: --hostname and --netconf work here as in build (default hostname saphira on OpenRC targets, saphirad on systemd).
  • The root password: --root-password PW works, but consider spending it at the console instead. Leaving it unset means the first-boot wizard takes the password on the machine itself, typed where it never travels the network; a password set at install time rides inside the image and is visible as a command-line argument.

What differs from image builds

  • There is no --output or --size: the disk's own capacity is the size.
  • --allocate and --root-size behave as in build; the remainder of the device stays unallocated for later growth.
  • Partition device naming follows the kernel rule (a trailing digit on the disk name takes a p separator: /dev/sda1 versus /dev/nvme0n1p1), and the tool handles it, not by you.
  • grub-install targets the whole disk: --target=i386-pc for BIOS, --target=$ARCH-efi with --efi-directory=/boot/efi --removable --recheck for UEFI.
  • UEFI installs use the removable fallback path (BOOTX64.EFI): no NVRAM entry is written, so installation works where firmware variables are unreachable. Writing a boot entry with efibootmgr remains a deliberate follow-up, not a silent requirement.
  • Everything else is identical to the image path: installer, identity replay, init preparation, service enablement, PARTUUID-stable bootloader and final report.