Kryonux handbook
Installing Kryonux v0.0.0 on x86_64.
1. About Kryonux
Kryonux is a fast hardened x86_64 linux: openrc, the kryonk kernel based on kernel.org, limine, packages built from source with kpkg. It installs from the live iso with one command and boots to a plain console.
| Parameter | Value |
|---|---|
| Architecture | x86_64 |
| libc | glibc |
| Init | OpenRC |
| Kernel | kryonk based on kernel.org, disk and filesystem drivers built in; initramfs is needed only for luks2 |
| Bootloader | Limine |
| Filesystems | ext4 and btrfs (zstd) |
| Packages | From source only, the kpkg command |
1.1 Requirements
| Item | Guideline |
|---|---|
| CPU | Any x86_64, one image for all |
| RAM | 2 Gb or more |
| Disk | 10 Gb or more, 20 gb if you build packages |
| Boot | UEFI or bios (up to 2 tb in bios) |
| Network | Wired dhcp or wifi through iwctl |
| Media | Usb stick or disc with the live iso |
1.2 What is inside
GCC, glibc, binutils, python, openrc, udev, dhcpcd, iwd for wifi, opendoas instead of sudo, curl, git, nano, wget, rsync, openssh (disabled), nftables, gnupg, man-db, dosfstools, kpkg. No graphics or desktop.
1.3 What is tuned for speed and security
| Area | What is done |
|---|---|
| Boot speed | Without encryption the kernel boots without initramfs: disks and ext4/btrfs are built in, openrc starts services in parallel, the kernel is zstd compressed |
| Runtime speed | noatime, btrfs with zstd compression, tcp bbr, bfq, kyber and deadline disk schedulers, schedutil, zswap and zram with zstd, thp on request only |
| Kernel | KSPP-style options: randomization, hardened usercopy, memory init, enforced module signatures, yama ptrace_scope 2, kexec, devkmem and vsyscall disabled |
| Network | nftables with a drop policy on from the first boot, ssh off, sysctl against spoofing, redirects and source routing |
| Access | Admin commands through doas and the wheel group, the root password is set during install, no default passwords |
-march=native, so it runs on any x86_64. If needed, the iso can be built for x86-64-v3, which requires a cpu with avx2.1.4 What is not there yet
There is no graphics. Scripts for secure boot with your own keys, a signed uki and luks2 with tpm2 exist (see 5.6), but they have not been tested on real hardware yet. AppArmor is built into the kernel, no profiles are shipped. A cis check profile exists, selinux does not. Honestly: no system is unhackable, Kryonux gives a hardened baseline, not a guarantee.
2. Preparation
2.1 Writing the iso to a stick
Download the iso and checksum from the releases page and verify:
sha256sum -c kryounix-live-amd64-0.0.0.iso.sha256
Write the image to the stick (careful: pick the stick, its data will be erased):
sudo dd if=kryounix-live-amd64-0.0.0.iso of=/dev/sdX bs=4M status=progress conv=fsync
2.2 Logging in to the live system
Boot from the stick. Login is automatic: user kryounix, password kryounix, root through doas -s. This is for the live system only, ssh is closed for these accounts and the firewall is on.
2.3 Network
The install itself needs no network. Wired comes up by itself. Wifi:
doas iwctl station wlan0 scan
doas iwctl station wlan0 get-networks
doas iwctl station wlan0 connect network_name
ip addr
ping -c1 github.com
3. One-command install
In the live system run:
doas kryounix-install
The installer asks for the disk, filesystem (ext4 or btrfs), hostname, username and two passwords. Then it does everything itself:
- Partitions the disk: gpt with a 512 mb efi partition for uefi, dos with a 512 mb boot partition for bios, the rest is root
- Formats the partitions and mounts them at
/mnt/kryounix - Unpacks the system from the iso with
unsquashfs - Writes fstab, installs limine and the kernel into
/boot - Removes live leftovers, creates the user and passwords
- Checks the result and unmounts the disk
The installer first asks for the mode. Auto wipes the whole disk you pick. Manual lets you partition yourself with cfdisk, fdisk or sfdisk, then asks for the boot partition (efi system partition on uefi, vfat, 100 mb or more) and the root partition (4 gb or more). Only those two partitions are touched, all other partitions and their data stay intact. An existing vfat boot partition can be kept as is, the old fallback loader is saved as BOOTX64.EFI.bak. For scripts: KRYOUNIX_MODE=manual KRYOUNIX_ROOT=/dev/sda3 KRYOUNIX_BOOT=/dev/sda1 KRYOUNIX_FORMAT_BOOT=0.
When you see the done message run reboot and remove the stick. For scripts the installer takes variables instead of questions, see kryounix-install --help.
4. Manual install
The same thing kryounix-install does, step by step. Use it for a custom layout or to see how it works. Run as root (doas -s). /dev/sda below is an example, check your disk with lsblk.
4.1 Partitioning
sfdisk /dev/sda <<EOF
label: gpt
,512M,U
,,L
EOF
sfdisk /dev/sda <<EOF
label: dos
,512M,c,*
,,L
EOF
nvme0n1p1 and nvme0n1p2.4.2 Filesystems and mounting
mkfs.vfat -F32 /dev/sda1
mkfs.ext4 /dev/sda2
mkdir -p /mnt/kryounix
mount -o noatime /dev/sda2 /mnt/kryounix
btrfs with compression can replace ext4:
mkfs.btrfs /dev/sda2
mount -o noatime,compress=zstd:1 /dev/sda2 /mnt/kryounix
4.3 Unpacking the system
unsquashfs -f -d /mnt/kryounix /media/cdrom/kryounix/rootfs.squashfs
mkdir -p /mnt/kryounix/{proc,sys,dev,run,tmp,var/tmp,mnt,media}
chmod 1777 /mnt/kryounix/tmp /mnt/kryounix/var/tmp
mount -o umask=0077 /dev/sda1 /mnt/kryounix/boot
cp /media/cdrom/boot/vmlinuz /mnt/kryounix/boot/vmlinuz
If the iso is not mounted at /media/cdrom, check findmnt.
4.4 fstab
blkid /dev/sda1 /dev/sda2
Take the UUID and PARTUUID values from the output. File /mnt/kryounix/etc/fstab:
UUID=ROOT_UUID / ext4 noatime,errors=remount-ro 0 1
UUID=UUID_BOOT /boot vfat umask=0077,noatime 0 2
tmpfs /tmp tmpfs nosuid,nodev,mode=1777 0 0
4.5 Limine bootloader
mkdir -p /mnt/kryounix/boot/limine
nano /mnt/kryounix/boot/limine/limine.conf
Content (root partition PARTUUID from blkid, your filesystem type):
timeout: 3
/Kryonux
protocol: linux
path: boot():/vmlinuz
cmdline: root=PARTUUID=PARTROOT_UUID rootfstype=ext4 rw quiet slab_nomerge init_on_alloc=1 page_alloc.shuffle=1 randomize_kstack_offset=on vsyscall=none debugfs=off pti=on module.sig_enforce=1
mkdir -p /mnt/kryounix/boot/EFI/BOOT
cp /usr/share/limine/BOOTX64.EFI /usr/share/limine/BOOTIA32.EFI /mnt/kryounix/boot/EFI/BOOT/
cp /usr/share/limine/limine-bios.sys /mnt/kryounix/boot/limine/
limine bios-install /dev/sda
4.6 Configuration inside
mount --rbind /dev /mnt/kryounix/dev
mount -t proc proc /mnt/kryounix/proc
mount --rbind /sys /mnt/kryounix/sys
mount -t tmpfs tmpfs /mnt/kryounix/run
chroot /mnt/kryounix /bin/bash
Inside the chroot remove live leftovers, create the user and passwords:
rm -f /etc/init.d/kryounix-smoke /etc/runlevels/default/kryounix-smoke /etc/conf.d/agetty.tty1 /etc/ssh/sshd_config.d/05-kryounix-live.conf
userdel -r kryounix
useradd -m -G wheel,users,video,audio,netdev -s /bin/bash name
passwd name
passwd
echo "permit persist :wheel" > /etc/doas.conf
chmod 600 /etc/doas.conf
echo 'hostname="kryounix"' > /etc/conf.d/hostname
4.7 Finishing
exit
umount -R /mnt/kryounix
reboot
5. After the install
5.1 Login and rights
Log in as the user you created. Root commands go through doas:
doas kpkg install nano
5.2 Timezone and hostname
ls /usr/share/zoneinfo
doas ln -sfv /usr/share/zoneinfo/Europe/Moscow /etc/localtime
date
5.3 Network
dhcpcd gets an address by itself. For wifi:
doas iwctl station wlan0 connect network_name
ip addr
A static address goes into /etc/dhcpcd.conf.
5.4 Services and firewall
rc-update show
doas rc-service sshd start
doas rc-update add sshd default
doas kryounix-firewall status
doas kryounix-audit
SSH is off by default and the nftables firewall runs with a drop policy. Open the port with kryounix-firewall before enabling sshd (run kryounix-firewall with no arguments for help).
5.5 Swap and zram
Swap is optional. As a file:
doas dd if=/dev/zero of=/swapfile bs=1M count=4096 status=progress
doas chmod 600 /swapfile
doas mkswap /swapfile
doas swapon /swapfile
Plus a line in /etc/fstab: /swapfile none swap defaults 0 0. The kernel supports zswap and zram with zstd.
5.6 Hardening: apparmor, uki, tpm2, cis
The secure boot, uki and tpm2 scripts below are in the repository, but they have not been tested on real hardware yet.
AppArmor is built into the kernel. No userspace tools or profiles are shipped. Profiles and userspace are installed separately; after that a profile is enabled with aa-enforce and the state is checked with aa-status.
Signed uki: kernel, initramfs and kernel command line in one file signed with your db key. Enable it at install time (KRYOUNIX_SECUREBOOT=1 KRYOUNIX_UKI=1) or later: doas kryounix-uki build && doas kryounix-secureboot sign. The command line is baked in and cannot be changed at boot. Repeat after every kernel update.
TPM2 for luks: doas kryounix-tpm2 enroll seals the disk key in the tpm2 against pcr 7 (secure boot state) and adds luks slot 7. Run it when secure boot is already on and you booted with it. If keys change, secure boot is turned off or the disk moves, the tpm will not release the key and the system asks for the luks passphrase. The passphrase always keeps working, store it. Remove: doas kryounix-tpm2 remove.
CIS profile: doas kryounix-audit --cis adds checks for file permissions, passwords, disabled rare filesystems, network settings and ssh. These are checks inspired by the cis benchmark, not a certification.
6. Packages and kpkg
kpkg builds packages from source using its own recipes.
doas kpkg sync
kpkg search name
kpkg info name
doas kpkg install name
doas kpkg remove name
doas kpkg upgrade
doas kpkg clean
If a package fails, read the last log lines and look in errors and fixes. Builds need free space in /var/tmp and enough ram.
7. Your own kernel (optional)
The kernel from the iso fits most machines and needs no tuning. Build your own only if you need a driver the image lacks. GCC, make and the rest are already installed.
cd /usr/src
curl -LO https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.18.10.tar.xz
tar xf linux-6.18.10.tar.xz
cd linux-6.18.10
zcat /proc/config.gz > .config 2>/dev/null || make defconfig
make menuconfig
make -j$(nproc)
doas make modules_install
doas cp arch/x86/boot/bzImage /boot/vmlinuz-6.18.10
Add a second entry to /boot/limine/limine.conf with path: boot():/vmlinuz-6.18.10 and reboot. The disk driver and root filesystem must be built in (=y): without encryption there is no initramfs. The cmdline has module.sig_enforce=1: modules of your own kernel must be signed or the parameter removed.
8. Maintenance
doas kpkg sync
doas kpkg upgrade
doas kpkg clean
df -h
System updates ship as new live iso versions: reinstall or update packages with kpkg. Backup:
doas tar cpf /mnt/usb/kryounix-backup.tar.xz --xattrs-include='*.*' --numeric-owner --one-file-system -I xz /
9. Errors and fixes
| Problem | What to do |
|---|---|
| Installer says mkfs.btrfs is missing | This iso has no btrfs-progs, choose ext4 |
| Installer sees no disk | Check lsblk. The iso media is excluded on purpose |
| UEFI does not boot after install | Pick the disk in the firmware boot menu. The file must be at /boot/EFI/BOOT/BOOTX64.EFI |
| Kernel panic: unable to mount root | Compare root=PARTUUID= in limine.conf with blkid. Controllers other than sata, nvme, virtio and usb storage may need your own kernel, see 7 |
| No wifi | doas iwctl station wlan0 scan, then connect. Firmware is already in the system |
| Forgot the password | Boot the live iso, mount root at /mnt/kryounix, chroot, passwd |
| A package failed to build | doas kpkg sync and retry. If it fails, post the last log lines on the forum |
10. Cheat sheet
| Command | What it does |
|---|---|
doas kryounix-install | Install to disk |
doas -s | Root shell |
kpkg install name | Install a package |
rc-update show | Services by runlevel |
rc-service name restart | Restart a service |
kryounix-firewall status | Firewall state |
kryounix-audit | Security settings check |
iwctl | Wifi |
lsblk -f | Disks and filesystems |
11. Questions
Can it run on a server
Yes, with honest limits in mind: updates are manual. kpkg update verifies signatures, but no apparmor profiles or userspace tools are shipped: you add and enable your own. For critical systems judge the risks yourself.
Where to download the image
The live iso and checksums are published in the releases on the releases page, the current project version is 0.0.0. The installer is already inside the image, no separate archives are needed.
Is secure boot available
The scripts exist: KRYOUNIX_SECUREBOOT=1 in the installer and the kryounix-secureboot command (own keys, signed limine, kernel hashes). A signed unified kernel image is added with KRYOUNIX_UKI=1. This chain has not been tested on real hardware yet.