Skip to main content

In today’s tutorial, we’ll see how to use Kernel Boot in Nitrux.

Difficulty: ★★☆☆☆

📜 Table of Contents

  1. Introducing Kernel Boot
    1. What is Kernel Boot
    2. What Kernel Boot is not
  2. Using Kernel Boot in Nitrux
    1. Using kernels from Distrobox containers
      1. Using kernels from Distrobox containers with LUKS partitions
      2. Additional and Misc. Information
  3. Using Kernel Boot with NVIDIA graphic processors

Introducing Kernel Boot

The Kernel Boot (kboot) utility uses kexec and is designed for Nitrux OS to provide a solution to make it friendlier to load other Linux kernels on the fly.

⚠️ Important: Kernel Boot (kboot) is intended to work exclusively in Nitrux OS, and using this utility in other distributions will break them or not work at all. Please do not open issues regarding this use case; they will be closed.

Kernel Boot is designed for a particular purpose, making it easier to transition from the currently running kernel to a new kernel and avoiding the time-consuming hardware initialization and bootloader stages. It performs the following steps:

    1. Reads the settings in the specified configuration file.
    2. Then, it uses kexec to load the selected kernel using the parameters from the configuration file.

Introducing Kernel Boot.

What is Kernel Boot

What Kernel Boot is not

  • A bootloader.
    • Kernel Boot uses a mechanism for loading and executing a new kernel within an already running system, bypassing the complete boot process. In comparison, a bootloader such as GRUB is a full-featured bootloader responsible for the initial bootstrapping of the operating system. GRUB provides a menu to select the desired operating system or kernel.
  • An init or service manager.
    • Kernel Boot does not function as an init or replace an init. The init process is responsible for initializing the system, starting essential system services and daemons, and bringing up the user space environment. Kernel Boot does not perform these functions; Kernel Boot only loads a new kernel image.
  • An initrd or initram generator.
    • Kernel Boot does not replace or modify the existing initramfs generator. The initram generator tools like dracut or initramfs-tools are responsible for identifying and including the necessary modules, drivers, and scripts to correctly set up the root filesystem and handle any unique configurations (e.g., encrypted root, LVM, RAID, etc.). Kernel Boot loads a kernel and an existing initram image and transfers control to it.
  • A container, virtual machine, Live USB creator, Linux distribution, Live/Recovery/Rescue/Emergency environment, system installer, desktop environment, firmware, or “proprietary software.”
    • Note: We don’t know why anyone would think that, but one can never know, so let’s clarify that.

Using Kernel Boot in Nitrux

Kernel Boot is designed to be highly autonomous.



sudo kboot switch <config_file>
  • It switches the kernel using the settings in the specified configuration file, such as/etc/kboot.d/debian or /etc/kboot.d/liquorix.
    • ⚠️ Important: This process involves stopping the currently running kernel and starting the new kernel from scratch. All running processes, including the graphical session, are terminated during this transition.
    • ⚠️ Important: Kernel Boot is not a viable option for users of NVIDIA GPUs due to how the NVIDIA proprietary driver works with the Linux kernel. See Using Kernel Boot with NVIDIA graphic processors to use a different kernel.


Kernel Boot uses the directory /etc/kboot.d files to load kernels.

  • ⚠️ Important: The files in this directory must refer to a valid kernel (vmlinuz) and initram images (initrd.img) within the filesystem. We recommend putting kernel images other than the default kernel and initrd in the directory /kboot for better organization. In addition, to prevent polluting the GRUB menu.

Below is an example of a configuration file.

# Default values for booting a kernel with kboot
# 2023 (c) Nitrux Latinoamericana S.C.

# Define the path of vmlinuz and initrd to use with kexec.
# We suggest using the directory /kboot to organize kernels.
# Regular files and soft links are valid file types to use.

# Define the parameters used when loading the kernel.
# Kernel parameters go as a single line.
# NOTE: Do not use undeclared variables in the parameters. Doing so will prevent the kernel from loading.
# NOTE: Do not forget to include the root parameter. Otherwise, after running kboot, you will be staring at the initramfs.
# Use the command cat /proc/cmdline to view the UUID and the parameters. For example root=UUID=xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx


sudo kboot -h: Displays the help of kboot.
sudo kboot -d: Runs kboot in verbose mode.
sudo kboot -v: Displays the version of kboot.

Using Kernels from Distrobox containers

Installing a Linux kernel on a Distrobox container and using it with Kernel Boot is possible. To do this, we need to create a container using Distrobox. In this case, it is highly recommended to use a Debian-based container, as one of the differences between Linux distributions is module setups and configurations tailored to their specific system environments, e.g., initrd generation.

  • 🔰 Information: To learn how to manage software in Nitrux, see the tutorial about Software Management.

Let’s assume we use a container similar to that used in the tutorial to use Distrobox. To install the kernel package, run the following command.

  • ⚠️ Important: We’re using the Debian kernel as an example; however, users can install other Debian-packaged kernels like the vanilla Ubuntu kernel or the Canonical Mainline kernel. Please be aware that these kernel packages might have different dependency requirements than the kernel package in this tutorial. Additionally, be aware that the directory names will be different, i.e., 6.4.0-060400-generic instead of 6.4.0-1-amd64. Also, it might be the case that the initram is not generated when using these kernels; if that is the case, run update-initramfs -c -k all in the container.
#    Run the command without entering the container

distrobox-enter --name debian12-distrobox -- sudo apt install linux-image-amd64 linux-headers-amd64 dkms initramfs-tools

Then, we only copy the respective kernel image, initrd,, and config files in the container’s /boot directory to any directory on our home. And also the modules for that kernel.

  • 🔰 Information: Replace the version number of the files and directory accordingly; in the examples below, we installed the Debian kernel 6.4.0-1.
#    Run this command *outside of the container*

mkdir -p $HOME/boot/
mkdir -p $HOME/usr/lib/modules/

#    Run the commands without entering the container

distrobox-enter --name debian12-distrobox -- cp -r /boot/{vmlinuz,initrd.img,,config}-6.4.0-1-amd64 $HOME/boot
distrobox-enter --name debian12-distrobox -- cp -r /usr/lib/modules/6.4.0-1-amd64 $HOME/usr/lib/modules/

Next, since we’re using the Debian kernel, we will copy or move these files to the directory /kboot/debian (the directory in the root can have any name; however, for the sake of organization, we use /kboot/debian).

#    Enter the overlay and add the files to the Kernel Boot directory; do this on a separate tab if you've entered the container
#    Replace $USER with your username

sudo overlayroot-chroot

mount -t auto $(findfs LABEL=NX_HOME) /home

cp -r /home/$USER/boot/{vmlinuz,initrd.img,,config}-6.4.0-1-amd64 /kboot/debian
cp -r /home/$USER/usr/lib/modules/6.4.0-1-amd64 /usr/lib/modules

umount /home



#    Delete the files we copied to our home directory
#    Run this command *outside of the overlay*

rm -r $HOME/usr $HOME/boot

Using kernels from Distrobox containers with LUKS

The steps to use another kernel differ slightly when using encrypted partitions. We need to rebuild the initram of the kernel we’re adding so it knows there are encrypted partitions after copying the original initram file from the container. During installation, this is automatically done by Calamares for the default kernel.

To do this, run the following commands.

  • ⚠️ Important: The commands below assume that the kernel and initramfs are already in /boot.
#    Enter the overlay and update the initram so the LUKS configuration is loaded during boot

sudo overlayroot-chroot

mount -t devtmpfs dev /dev

update-initramfs -c -k 6.4.0-1-amd64

umount /dev



Additional and Misc. Information

Optionally, create soft links to /boot in the root directory so GRUB can add the kernel as a menu entry. If that is not wanted, don’t create the soft links and use Kernel Boot to switch the kernel.

#   Enter the overlay and create the links from /kboot to /boot

sudo overlayroot-chroot

mount -t devtmpfs dev /dev

ln -sv /kboot/debian/initrd.img-6.4.0-1-amd64 /boot/initrd.img-6.4.0-1-amd64
ln -sv /kboot/debian/vmlinuz-6.4.0-1-amd64 /boot/vmlinuz-6.4.0-1-amd64
ln -sv /kboot/debian/ /boot/
ln -sv /kboot/debian/config-6.4.0-1-amd64 /boot/config-6.4.0-1-amd64


umount /dev



Using Kernel Boot with NVIDIA graphic processors

The steps below are necessary if the device uses NVIDIA hardware since Kernel Boot will not work with it for the reasons we mentioned earlier (for more information, see this issue). First, we need to copy the header files of the kernel we intend to use to a directory that our user can access, like our home.

#    Run the commands without entering the container

distrobox-enter --name debian12-distrobox -- cp -r /usr/src/linux-headers-6.4.0-1-amd64 $HOME/usr/src/

Then, we copy the directory in $HOME/usr/src/ to the /usr/src in our root. Finally, run DKMS so it can build the driver for the specified kernel and exit the overlay.

  • ⚠️ Important: To copy, move, or edit files in the root directory, see XFS Features and Root Immutability in Nitrux.
  • ⚠️ Important: DKMS will fail to build the modules of the NVIDIA proprietary driver if the kernel is too new. This is not a bug in Nitrux or caused by Nirux.
  • ⚠️ Important: DKMS will fail to build the modules of the NVIDIA proprietary driver when using the signed Debian kernel, which differs from the non-signed kernel used in this tutorial and the Liquorix kernel used by default (for more information, see this issue). This is not a bug in Nitrux or caused by Nirux.
#  Enter the overlay and copy the headers to the root

sudo overlayroot-chroot

mount -t devtmpfs dev /dev
mount -t auto $(findfs LABEL=NX_HOME) /home

cp -r /home/$USER/usr/src/linux-headers-6.4.0-1-amd64 /usr/src

# Replace the version number with the correct version number of the currently installed driver

dkms install nvidia/545.29.06 -k 6.4.0-1-amd64

umount /dev /home



To pass kernel parameters to the newly added kernel, edit the file /etc/default/grub and run update-grub afterward.

That’s it; this concludes today’s tutorial.