Saphira Linux v0 Bootstrap

You need two things: an existing Linux system that is already running, and a spare target disk that you are willing to erase. The existing system is the host. It is where you download and unpack the Bootstrap release, identify the disk, partition it, mount it and start the installation.

sudo -i
mkdir -p /root/saphira-bootstrap
cd /root/saphira-bootstrap
tar -xJf saphira-linux-v0.bootstrap.tar.xz
ls -la

After extraction you should see README-INSTALL.md, README-KERNEL.md and saphira.rootfs.x86-64-v3/. Read the disk steps once before running them. The examples use /dev/sdX as a deliberately fake disk name; never type it literally.

Commands marked as host commands run on the existing Linux system. Commands after saphira-chroot /mnt/saphira run inside the new Saphira filesystem. The chroot is not a virtual machine and does not boot a new kernel.

lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS,MODEL
findmnt
blkid

Find the spare disk by its size, model and current mount points. The installation below formats a partition and installs GRUB to the disk. A mistake here can destroy the host operating system or somebody else's data. If you are unsure which device is the spare disk, stop and identify it before continuing.

• Do not use the host's mounted root disk as /dev/sdX.
• Do not run mkfs or grub-install until the device has been checked twice.
• Back up anything on the target disk that matters; this process is destructive.

The Bootstrap archive contains the Saphira x86-64-v3 root filesystem, installation and kernel documentation, the rootfs archive, checksums, and a bundled Linux 7.2 source archive with its SHA-256 checksum and PGP signature.

This is not a pre-built installer image. You prepare the target disk from another Linux system, copy the root filesystem onto it, generate its filesystem table, install GRUB, and create a fresh target-specific GRUB configuration.

Saphira userspace requires x86-64-v3. The requirement comes from musl and the compiled userspace binaries, not from the kernel alone.

• AVX2, BMI1, BMI2, FMA, F16C, LZCNT and MOVBE, plus the x86-64-v2 baseline.
• Intel Haswell (2013) or newer is a useful rough guide.
• AMD Excavator or Zen (2015) or newer is a useful rough guide.
• Older CPUs may boot the kernel but userspace will stop with Illegal instruction.

lscpu | grep -o -e avx2 -e bmi1 -e bmi2 -e fma -e f16c -e movbe

All six names must be present before installing. Check the target machine, or the host when the target is a virtual machine.

Use an already-running Linux system with root access and a target disk you are prepared to wipe. Identify the target carefully; the example device name is deliberately not a real disk.

lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS,MODEL
fdisk /dev/sdX
mkfs.ext4 /dev/sdX1
e2label /dev/sdX1 saphira
mkdir -p /mnt/saphira
mount /dev/sdX1 /mnt/saphira
findmnt /mnt/saphira

For UEFI, create a GPT table, a FAT32 EFI system partition mounted at /boot/efi, and a root partition. BIOS installation uses GRUB on the whole disk and is the simple KVM/QEMU path.

From the directory containing the extracted Bootstrap release, copy the contents of the root filesystem into the mounted target. The trailing /. is important: it avoids creating an extra rootfs directory on the target.

cp -a saphira.rootfs.x86-64-v3/. /mnt/saphira/
ls /mnt/saphira

The target should now contain directories such as bin, boot, dev, etc, lib, root, run, sbin, usr and var. The files are present, but the disk is not bootable until fstab and GRUB are configured.

saphira-genfstab /mnt/saphira > /mnt/saphira/etc/fstab
cat /mnt/saphira/etc/fstab
saphira-chroot /mnt/saphira

Read the generated fstab before continuing. saphira-genfstab prefers UUID and PARTUUID entries. saphira-chroot binds the required /dev, /dev/pts, /proc, /sys, /run and resolver paths in a private mount namespace, then enters the copied filesystem.

Inside the chroot, paths refer to the target filesystem. The running kernel is still the host kernel; do not use uname in the chroot as evidence that the target kernel is running.

saphira-chroot /mnt/saphira apk info
saphira-chroot /mnt/saphira /bin/sh

The copied root filesystem contains APK and its initial repository configuration. The Bootstrap guide keeps the local package cache available and allows the live Saphira repository to be added inside the chroot before refreshing the index.

grep -q 'packages.akadata.ltd/saphira/main' /etc/apk/repositories || \
  echo 'https://packages.akadata.ltd/saphira/main/' >> /etc/apk/repositories
apk update
apk add <package>

This step can be done before rebooting in the chroot or after the first boot. The chroot needs working network and DNS through the host.

The root filesystem retains a usable reference kernel, configuration and modules so the freshly bootstrapped system has a fallback path while you work on your own kernel.

• /boot/vmlinuz-7.1.5-akadata
• /boot/config-7.1.5-akadata
• /lib/modules/7.1.5

The preferred development path is to build Linux 7.2 from the bundled verified source. The source lives in /usr/src with four files: README.md, linux-7.2.tar.xz (the compressed source), linux-7.2.tar.xz.sha256 (its checksum) and linux-7.2.tar.sign (its PGP signature).

cd /usr/src
sha256sum -c linux-7.2.tar.xz.sha256
gpg --verify linux-7.2.tar.sign linux-7.2.tar.xz
tar -xJf linux-7.2.tar.xz
cd linux-7.2
cp /boot/config-7.1.5-akadata .config
make olddefconfig
make -j$(nproc)
make modules_install
make install

The PGP signature is for the uncompressed tar archive represented by the signed source release. Import and trust the kernel.org signing key separately before relying on that verification.

The target needs a new filesystem-specific GRUB configuration. Do not copy or rely on an old boot/grub/grub.cfg from another installation.

# BIOS / legacy boot
grub-install /dev/sdX
grub-mkconfig -o /boot/grub/grub.cfg
cat /boot/grub/grub.cfg

For UEFI, use the target's mounted EFI system partition and the Saphira bootloader ID, then regenerate the same target-specific grub.cfg.

grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=Saphira
grub-mkconfig -o /boot/grub/grub.cfg

Leave the chroot, unmount the target cleanly, detach it from the host as appropriate, and boot the target disk. Saphira's first-boot setup then asks for the root password, normal user, networking, DNS and APK repository configuration.

exit
umount -R /mnt/saphira
reboot

The installed helper tools are ordinary shell scripts. Read them when you need to understand or adapt the process:

• /usr/bin/saphira-bootstrap
• /usr/bin/saphira-chroot
• /usr/bin/saphira-genfstab

The first boot runs akadata-firstboot. It asks for the root password, creates the normal user, configures IPv4 and IPv6, selects DNS, and confirms the Saphira APK repository. It then leaves you at a normal shell.

apk update
apk search node
apk add node

If the machine does not boot, use the troubleshooting section below and change one thing at a time rather than several at once.

• Illegal instruction early in boot: confirm all x86-64-v3 CPU features are present.
• GRUB reports no Linux image: check ls /boot/vmlinuz-* inside the target and regenerate grub.cfg.
• GRUB stops at a prompt: repeat grub-install for the correct whole disk, then run grub-mkconfig again.
• No DNS in the chroot: saphira-chroot binds the host resolver; repair host DNS first.
• apk update fails: check /etc/apk/repositories, DNS, routing and access to the Saphira repository.

If a new kernel fails on a KVM x86-64-v3 guest, select the original 7.1.5-akadata kernel from GRUB's Advanced options. On a physical machine or a different hypervisor, that fallback will not boot either, so fix and rebuild your own 7.2 kernel instead. Either way, do not delete /lib/modules/7.1.5 until the new kernel has booted and its hardware support has been checked.