Disclaimer:
This guide is not for the faint of heart! It assumes that you have some idea of what a statically linked kernel is, and how to build one for your hardware in a source-based distribution.
This page was last updated on January 22, 2024 (as of May 19, 2025) and may not be up to date (e.g., pkgs/bin/kernel/kernels.json was removed on January 27, 2024).
Also you can use any suitable kernel for your hardware that:
This guide assumes that the IX package manager is in your PATH:
ix# export PATH=/mnt/ix/home/ix/ix:${PATH} # assumes we are in stal/IX installer, before reboot
ix# export PATH=/home/ix/ix:${PATH} # assumes we are in stal/IX installer, after reboot
ix# export PATH=/your/local/checkout:${PATH} # assumes local ix checkout per user
ix# ix list
The goal of this guide is to build a kernel that contains all the components needed to run it.
First, you need to know the list of modules that your hardware supports.
To do this, you can download any regular distribution with a working automatic hardware detection system.
You need to do the following:
ubuntu# lspci -k
03:00.0 Class 0300: 1002:1638 amdgpu
02:00.0 Class 0108: 144d:a809 nvme
03:00.7 Class 1180: 1022:15e4 pcie_mp2_amd
03:00.5 Class 0480: 1022:15e2 snd_rn_pci_acp3x
01:00.0 Class 0280: 8086:2723 iwlwifi
03:00.3 Class 0c03: 1022:1639 xhci_hcd
03:00.1 Class 0403: 1002:1637 snd_hda_intel
00:08.1 Class 0604: 1022:1635 pcieport
00:02.4 Class 0604: 1022:1634 pcieport
03:00.6 Class 0403: 1022:15e3 snd_hda_intel
00:02.2 Class 0604: 1022:1634 pcieport
03:00.4 Class 0c03: 1022:1639 xhci_hcd
03:00.2 Class 1080: 1022:15df ccp
00:14.0 Class 0c05: 1022:790b piix4_smbus
00:08.2 Class 0604: 1022:1635 pcieport
...
The last column is a list of modules we need. Write them down.
Next, we need to prepare a directory with the kernel sources for which we are building a config. Let’s say we want to use kernel 6.0:
ix# mkdir kernel
ix# cd kernel
# get current linux kernel source
ix# cat $(dirname $(which ix))/pkgs/bin/kernel/kernels.json | grep https
...
"url": "https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.7.1.tar.xz",
...
ix# wget https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.7.1.tar.xz
ix# tar xf linux-6.7.1.tar.xz
ix# cd linux-6.7.1
Let’s copy the old kernel configuration into our tree:
ix# cp $(dirname $(which ix))/pkgs/bin/kernel/configs/cfg_6_6_0 ./.config
Run the kernel configurator:
ix run set/menuconfig -- make HOSTCC=cc menuconfig
You need to find all the modules from the list above in the configurator (there is a search!) and add them to the configuration.
That being said:
dmesg | grep firmware on a running system to get information about the missing firmware!Alternatively, you can combine the previous commands into one:
...
ix# cd linux-6.7.1
ix# ix tool reconf $(dirname $(which ix))/pkgs/bin/kernel/configs/cfg_6_6_0
Most often, to understand what needs to be included in the kernel configuration for a particular device operation, it is useful to search the web for the module name and the Gentoo/Arch link, as they have the largest knowledge base on the topic:
After configuring the kernel, copy the modified configuration to the base:
ix# cp .config $(dirname $(which ix))/pkgs/bin/kernel/configs/cfg_6_6_0
After that, you can add the kernel to the system realm in the usual way:
ix# ix mut system bin/kernel/6/7
ix# ls /bin/kernel-*
/bin/kernel-6-7-1...
Remember that path, you will need it later in GRUB CLI or in grub.cfg.
Alternatively, you can use a separate realm for the bootstrap kernel:
ix# ix mut kernel bin/kernel/6/7
ix# ls /ix/realm/kernel/bin/kernel-*
/ix/realm/kernel/bin/kernel-6-7-1-slot0
Remember that path, you will need it later in GRUB CLI or in grub.cfg.