Kryonuxhandbook

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.

ParameterValue
Architecturex86_64
libcglibc
InitOpenRC
Kernelkryonk based on kernel.org, disk and filesystem drivers built in; initramfs is needed only for luks2
BootloaderLimine
Filesystemsext4 and btrfs (zstd)
PackagesFrom source only, the kpkg command

1.1 Requirements

ItemGuideline
CPUAny x86_64, one image for all
RAM2 Gb or more
Disk10 Gb or more, 20 gb if you build packages
BootUEFI or bios (up to 2 tb in bios)
NetworkWired dhcp or wifi through iwctl
MediaUsb 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

AreaWhat is done
Boot speedWithout encryption the kernel boots without initramfs: disks and ext4/btrfs are built in, openrc starts services in parallel, the kernel is zstd compressed
Runtime speednoatime, btrfs with zstd compression, tcp bbr, bfq, kyber and deadline disk schedulers, schedutil, zswap and zram with zstd, thp on request only
KernelKSPP-style options: randomization, hardened usercopy, memory init, enforced module signatures, yama ptrace_scope 2, kexec, devkmem and vsyscall disabled
Networknftables with a drop policy on from the first boot, ssh off, sysctl against spoofing, redirects and source routing
AccessAdmin commands through doas and the wheel group, the root password is set during install, no default passwords
Note the default image is built without -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:

  1. 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
  2. Formats the partitions and mounts them at /mnt/kryounix
  3. Unpacks the system from the iso with unsquashfs
  4. Writes fstab, installs limine and the kernel into /boot
  5. Removes live leftovers, creates the user and passwords
  6. 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.

Important in auto mode the chosen disk is erased completely, in manual mode only the root partition (and the boot partition if you format it). The installer refuses the media the iso booted from and asks you to type the disk path to confirm.

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
Important all data on the chosen disk is erased. On nvme the partitions are named 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

ProblemWhat to do
Installer says mkfs.btrfs is missingThis iso has no btrfs-progs, choose ext4
Installer sees no diskCheck lsblk. The iso media is excluded on purpose
UEFI does not boot after installPick the disk in the firmware boot menu. The file must be at /boot/EFI/BOOT/BOOTX64.EFI
Kernel panic: unable to mount rootCompare root=PARTUUID= in limine.conf with blkid. Controllers other than sata, nvme, virtio and usb storage may need your own kernel, see 7
No wifidoas iwctl station wlan0 scan, then connect. Firmware is already in the system
Forgot the passwordBoot the live iso, mount root at /mnt/kryounix, chroot, passwd
A package failed to builddoas kpkg sync and retry. If it fails, post the last log lines on the forum

10. Cheat sheet

CommandWhat it does
doas kryounix-installInstall to disk
doas -sRoot shell
kpkg install nameInstall a package
rc-update showServices by runlevel
rc-service name restartRestart a service
kryounix-firewall statusFirewall state
kryounix-auditSecurity settings check
iwctlWifi
lsblk -fDisks 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.