RTFM · Troubleshooting

Initial setup checks

A first-boot checklist for a fresh Saphira installation: confirm what you are running, confirm the disk layout survived, and fix the small things before they become the big things.

Answer three questions first

Most install problems resolve to three questions: which build did I actually boot, which network configuration was applied, and did any stage report a failure I skipped past? Gather that evidence before changing anything.

Evidence gathering

# What am I running?
cat /etc/os-release
uname -a

# Which release series is installed?
apk list --installed | head

# Anything logged during the last boot?
dmesg | tail -50

Confirm the root filesystem

The bootstrap installs a staged root. If the wrong stage was unpacked, the symptom usually appears at first boot or first apk invocation rather than during install.

1. Check the ABI the system expects
cat /etc/os-release and read the ID fields. Compare against the bootstrap release notes.
2. Check whether /boot matches the running kernel
uname -r must exist as /boot/vmlinuz-* of the same version. A mismatch means GRUB booted a different entry than you think.
3. Re-run verification if unsure
Compare checksums of the downloaded bootstrap archive again before reinstalling anything.

Prove it works: fresh install identity

you know the exact build you booted, the exact kernel version, and there are no unexplained dmesg errors from the storage controller.

First-boot service state

Saphira uses OpenRC. Services may be stopped rather than failed; rc-status shows the difference between never started, stopped deliberately, and crashed.

Service and resource sanity

rc-status --all
top -b | head
free -m

Time and entropy

Wrong clocks break TLS, DNSSEC validation, and package signatures indistinguishably from genuinely broken packages. Set time correctly before diagnosing anything else.

Clock sanity

# Check clock drift
date
hwclock --show

# Correct it
hwclock --hctosys   # or --systohc after fixing system time

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 →