Build a Saphira Linux kernel

A freshly bootstrapped Saphira system already contains /boot/vmlinuz-7.1.5-akadata, /boot/config-7.1.5-akadata and /lib/modules/7.1.5. If you are installing the Bootstrap as a KVM/QEMU guest with the same kind of virtual hardware as the reference image, install GRUB and use that kernel first.

If you are installing on physical hardware, or under a hypervisor with different virtual devices, plan to build a kernel before your first reboot. The retained 7.1.5-akadata kernel may not contain the storage, network, filesystem, chipset or virtual-device drivers that your target needs. Do not assume that a kernel which boots the KVM reference image will boot another machine.

Build Linux 7.2 when you need target hardware support, want to run the newer bundled kernel, or want to learn how the pieces fit together. Kernel compilation is separate from the x86-64-v3 userspace requirement: the kernel itself does not need to be compiled with -march=x86-64-v3, but the machine still needs x86-64-v3 for Saphira userspace.

• KVM/QEMU guest matching the reference image: the retained kernel is a useful first boot option, but keep the build guide available.
• Physical machine or different hypervisor: build and install Linux 7.2 before rebooting into the new disk.
• Build on a running Saphira system after first boot, or inside saphira-chroot /mnt/saphira before rebooting.
• Use enough free disk space for the extracted source, build output and installed modules.
• Use several GiB of RAM and as many CPU cores as practical; a kernel build can take time.
• Keep the known-good kernel and modules until the replacement has booted successfully.

Inside the Saphira root filesystem, the Linux source lives in /usr/src. After you unpack the Bootstrap release (or boot into an installed Saphira) that directory contains 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). README.md in that directory mirrors this guide and you can read it any time with less /usr/src/README.md.

You build the kernel either on an already-installed, running Saphira system, or from the host while you are still preparing the target disk, by entering the Saphira chroot. The chroot is a command (saphira-chroot) that opens a root shell inside the Saphira filesystem you copied to /mnt/saphira; it is not a virtual machine and it does not boot a new kernel.

# From the host, once the target disk is mounted and the rootfs copied:
saphira-chroot /mnt/saphira

# Or, on an already-installed Saphira, just open a terminal.
# Either way, continue from here:
cd /usr/src
ls

Confirm the four source files are present before going further. The next sections verify, extract and compile them.

ls -lh /usr/src/README.md /usr/src/linux-7.2.tar.xz /usr/src/linux-7.2.tar.xz.sha256 /usr/src/linux-7.2.tar.sign

The bundled toolchain covers the build itself. You only reach for apk when you want something extra — most commonly gnupg, which provides gpg for the optional PGP signature check in the next section. The copied root filesystem ships APK and a local package cache, but to fetch packages from the live Saphira repository you first add its address and refresh 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 gnupg

apk add <package> installs a package, apk update refreshes the package lists, and apk search <word> finds packages by name. These are normal commands you can read and understand; nothing here is hidden.

A kernel is built from source code by a compiler. The Saphira base image already includes everything that step needs: GCC (the C/C++ compiler), make (which orchestrates the build), plus bison, flex, perl, openssl and ncurses used by the build and configuration tools. The Linux 7.2 source, its SHA-256 checksum and its PGP signature all live in /usr/src, which you are already in from the previous step.

command -v gcc make bison flex perl openssl
gcc --version
cd /usr/src
ls -lh linux-7.2.tar.xz linux-7.2.tar.xz.sha256 linux-7.2.tar.sign

If a command is missing, add it with apk — see the "Install extra packages with apk" section above. Do not start by copying random tools from the host into the target; install them through the package manager so they stay tracked and consistent with the rest of the system.

You need to be root for the installation steps, but source verification and compilation can be done as an ordinary build user if /usr/src is writable. The commands below assume you are in the Saphira chroot or have already booted Saphira, and that /usr/src/linux-7.2 does not contain work you need to preserve.

cd /usr/src
cat linux-7.2.tar.xz.sha256
sha256sum -c linux-7.2.tar.xz.sha256
# expected: linux-7.2.tar.xz: OK
gpg --verify linux-7.2.tar.sign linux-7.2.tar.xz

First read the checksum file. It contains the expected SHA-256 digest followed by the exact filename. sha256sum -c calculates the digest again and compares it; continue only when it prints linux-7.2.tar.xz: OK. A different digest means the archive is incomplete, damaged or not the supplied file. Do not extract it.

The PGP signature is a second, independent check. A .sign file is not the public key: GPG must have the matching kernel.org public key in its keyring. Obtain that public key from a trusted kernel.org key source or from your organisation's trusted key distribution, inspect its fingerprint with gpg --show-keys, and compare the fingerprint with an independently trusted kernel.org reference before importing it. Never accept a fingerprint copied only from an untrusted download beside the archive.

# Example: verify a public key file supplied by a trusted source
gpg --show-keys --fingerprint kernel.org-key.asc
gpg --import kernel.org-key.asc
gpg --verify linux-7.2.tar.sign linux-7.2.tar.xz

Read the GPG result carefully. A good signature from a key you have independently verified is a pass. 'Good signature' with a warning that the key is not trusted means the cryptographic check worked but you have not established that the key belongs to kernel.org. 'BAD signature' or a missing public key is not a pass; stop and fix verification before extracting the archive.

cd /usr/src
tar -xJf linux-7.2.tar.xz
cd linux-7.2
make mrproper

make mrproper removes configuration files and generated output from a kernel tree. Run it before copying the base configuration into a fresh tree, not after you have made changes you want to keep.

make clean is less destructive: it removes most compiled output but normally keeps .config. Use it when rebuilding an existing tree after a failed or changed build. It is not a substitute for make mrproper when you need a genuinely clean starting point.

# Optional when reusing an existing tree
make clean

test -r /boot/config-7.1.5-akadata
cp /boot/config-7.1.5-akadata .config
make olddefconfig

The test confirms that the reference configuration exists. If it fails, you are not in the installed Saphira root filesystem or the reference configuration was removed; stop here rather than inventing a configuration. The supplied configuration matches the reference 7.1.5 kernel. olddefconfig keeps known settings and chooses defaults for options introduced by Linux 7.2, producing a complete configuration without hundreds of questions.

If you want to answer new configuration questions yourself, use make oldconfig instead. Read each prompt and accept the suggested default unless you understand why a change is needed.

# Interactive alternative
make oldconfig

make localmodconfig can remove drivers that are not currently loaded. That can make a kernel smaller, but it can also remove storage, network, filesystem or future hardware support. Use it only when you understand the trade-off, and inspect the resulting configuration before building.

# Optional and potentially restrictive
make localmodconfig

make menuconfig

menuconfig is optional. Use the arrow keys, read Help for an option, change what you understand, then choose Save and Exit. Pay particular attention to the storage controller, root filesystem, virtio-blk or NVMe for virtual machines, and the physical or virtio network driver. A built-in driver (=y) is available during early boot; a module (=m) must be installed and loaded.

For a physical machine, identify the hardware before choosing drivers: lspci -nn lists PCI devices, lsblk -f shows disks and filesystems, and ip link shows network interfaces. In menuconfig, search for the matching storage, filesystem and network drivers and prefer built-in support (=y) for the storage controller, root filesystem and anything needed before /lib/modules can be read. This is why a physical installation should not blindly reuse the KVM configuration.

make -j$(nproc)
KREL="$(make -s kernelrelease)"
echo "$KREL"

The build uses all available processor cores. It may take a while. KREL records the exact release string produced by the configuration; keep it for the installation commands instead of guessing a version number.

If compilation stops with missing headers or tools, read the first error, install the relevant build package, and run make again. Do not delete the working 7.1.5 fallback while diagnosing a build failure.

make modules_install
mkdir -p /boot
cp arch/x86/boot/bzImage "/boot/vmlinuz-${KREL}"
cp System.map "/boot/System.map-${KREL}"
cp .config "/boot/config-${KREL}"

modules_install places loadable modules under /lib/modules/$KREL. The manual copy places the kernel image, symbol map and matching configuration in /boot. The path is arch/x86/boot/bzImage; arch/x86/arch/bzImage is not the kernel image path.

Saphira also supplies an installkernel helper, so make install is the shorter alternative when it is available:

make modules_install
make install

Check that the expected files exist before changing GRUB:

ls -lh /boot/vmlinuz-* /boot/config-* /boot/System.map-*
ls -ld /lib/modules/${KREL}

grub-mkconfig -o /boot/grub/grub.cfg
cat /boot/grub/grub.cfg | grep vmlinuz

GRUB should list the new kernel and retain 7.1.5-akadata in its Advanced options. Do not copy an old grub.cfg from another disk or installation; regenerate it for this target so its filesystem references and kernel entries are correct.

If you are still completing the initial disk bootstrap, install GRUB to the whole BIOS disk with grub-install /dev/sdX, or use the UEFI command from the Bootstrap installation page before running grub-mkconfig.

reboot
uname -a
cat /proc/cmdline
ls /lib/modules/$(uname -r)

Select the new kernel in GRUB or let it boot by default. After boot, uname reports the kernel that is actually running. Test storage, networking and the services you rely on before making the new kernel the only option.

If your new kernel fails on a KVM x86-64-v3 guest, choose the known-good 7.1.5-akadata entry from GRUB's Advanced options, then inspect the new configuration, drivers and modules. Keep /boot/vmlinuz-7.1.5-akadata, /boot/config-7.1.5-akadata and /lib/modules/7.1.5 until your own kernel is proven.

• Build stops with a missing tool or header: read the first error, then install the package with apk add <name> (add the repository line first if needed — see the apk section). Do not copy tools from the host.
• make menuconfig reports a missing curses/ncurses library: install it with apk add ncurses and run make menuconfig again.
• gpg: command not found during signature verification: gpg is not in the base image; apk add gnupg, or skip the signature step — the SHA-256 checksum alone confirms the archive is intact.
• Boot hangs or drops to an emergency shell with no root device: your storage or root-filesystem driver is probably a module that is not loaded, or built for the wrong controller. Rebuild it into the kernel (=y) with make menuconfig, or ensure the module and its dependencies are in /lib/modules/$KREL.
• GRUB does not list the new kernel: check ls /boot/vmlinuz-* inside the target, then re-run grub-mkconfig -o /boot/grub/grub.cfg.
• The 7.1.5-akadata fallback will not boot on a physical machine or non-KVM hypervisor: that is expected — it only supports KVM x86-64-v3. Fix and rebuild your own 7.2 kernel instead of relying on it.