Kernel Replacement - minios-linux/minios-live GitHub Wiki

Guide to Replacing the Kernel in MiniOS

This guide explains how to replace the kernel in MiniOS. The process consists of two main parts:

Generating Kernel Files: The built-in minios-kernelpack script is used to create the necessary vmlinuz, initrfs, and SquashFS (.sb) files. The script can use a locally installed kernel or download one from a repository.
Deploying Kernel Files: Copying the generated files to the correct locations on the MiniOS USB drive and updating the bootloader configuration. Important: The file locations on the USB drive depend on how the MiniOS system is booted.

Important Considerations Before Starting:

Root Privileges: You must run the script as the root user (or using sudo). The deployment steps also require root access to the MiniOS USB drive.
Kernel Compatibility: Ensure that the kernel you choose is compatible with MiniOS. Using a kernel significantly different from the original may lead to instability or failure. It is recommended to use kernels from the MiniOS repository if available.
Bootloader: MiniOS uses Syslinux and GRUB as bootloaders. You must update both configurations to point to the new kernel and initramfs files.
Dependencies: When manually copying vmlinuz, the corresponding initrfs must be copied at the same time.

Part 1: Generating Kernel Files (Using minios-kernelpack)

The minios-kernelpack script automates the creation of:

vmlinuz-<kernel-version>: The kernel itself.
initrfs-<kernel-version>.img: The initial RAM file system (initramfs) with drivers and scripts for early boot.
01-kernel-<kernel-version>.sb: The SquashFS image containing the kernel modules (drivers).

Steps:

Running the Script: Execute minios-kernelpack as root. Beginners are advised to run the script without parameters (default compression methods are used – zstd).
```
sudo minios-kernelpack
```
The script will guide you through interactive prompts:
- Kernel Source: "local" (installed kernel) or "repository" (download from repository).
- Installed Kernel (if local): Select a kernel from the list in /lib/modules.
- Kernel from Repository (if repository): Select a kernel package. The script will update the package list.
By default, zstd compression is used for SquashFS and initramfs.
Advanced Options (Optional):
- Fully Interactive Mode:
```
sudo minios-kernelpack -c
```
  Will prompt for selection of compression methods for SquashFS and initramfs.
- Specifying Compression Methods:
```
sudo minios-kernelpack -s lz4 -i gzip
```
  Uses lz4 for SquashFS and gzip for initramfs. Available options: lz4, lzo, gzip, zstd, lzma, xz, bzip2.
Output Files: After the script completes, the files (vmlinuz-<kernel-version>, initrfs-<kernel-version>.img, 01-kernel-<kernel-version>.sb) will be in the same directory. An initramfs-<kernel-version>.log file might be created.

Part 2: Deploying Kernel Files (Manual Steps)

Install the new kernel files onto the MiniOS USB drive. Attention! The file locations depend on how MiniOS is booted:

Booting from USB (filesystem with read-write support, not in RAM): Files are located in /run/initramfs/memory/data/minios.
USB drive connected to another system: Files are located in /minios on the root partition of the USB drive.

Mount the USB Drive: If MiniOS is not booted from this USB drive, mount it:
```
sudo mkdir -p <mount_point>
sudo mount /dev/sdX1 <mount_point>  # Replace /dev/sdX1 with the correct partition
```
If MiniOS IS booted from the flash drive, remount the root filesystem in write mode:
```
 sudo mount -o remount,rw /
```

Copy the Files:

If MiniOS is booted from this USB drive:

sudo cp 01-kernel-<kernel-version>.sb /run/initramfs/memory/data/minios/
sudo cp vmlinuz-<kernel-version> /run/initramfs/memory/data/minios/boot/
sudo cp initrfs-<kernel-version>.img /run/initramfs/memory/data/minios/boot/

If MiniOS is not booted from this USB drive (USB drive connected to another system):

sudo cp 01-kernel-<kernel-version>.sb <mount_point>/minios/
sudo cp vmlinuz-<kernel-version> <mount_point>/minios/boot/
sudo cp initrfs-<kernel-version>.img <mount_point>/minios/boot/

Update the Bootloader Configuration: Modify syslinux.cfg and grub.cfg, pointing to the new kernel and initramfs files.
- Where to find the configuration files:
  - Booting from USB: /run/initramfs/memory/data/minios/boot/syslinux.cfg and /run/initramfs/memory/data/minios/boot/grub/grub.cfg
  - USB drive connected to another system: <mount_point>/minios/boot/syslinux.cfg and <mount_point>/minios/boot/grub/grub.cfg
- Edit syslinux.cfg:
```
sudo nano <path_to_syslinux.cfg>  # Use the correct path!
```
  Find the LABEL entries. Modify the kernel and append initrd= lines:
```
# Before:
# LABEL minios
#   KERNEL /minios/boot/vmlinuz-old-version
#   APPEND initrd=/minios/boot/initrfs-old-version.img ...

# After:
LABEL minios
  KERNEL /minios/boot/vmlinuz-<kernel-version>
  APPEND initrd=/minios/boot/initrfs-<kernel-version>.img ...
```
  Repeat for all LABEL entries. Do not remove other parameters in the APPEND line.
- Edit grub.cfg:
```
 sudo nano <path_to_grub.cfg> # Use the correct path!
```
  Find the menuentry blocks and modify linux and initrd:
```
# Before:
# menuentry "MiniOS" {
#   linux /minios/boot/vmlinuz-old-version ...
#   initrd /minios/boot/initrfs-old-version.img
# }

# After:
menuentry "MiniOS" {
  linux /minios/boot/vmlinuz-<kernel-version> ...
  initrd /minios/boot/initrfs-<kernel-version>.img
}
```
  Do not remove other parameters in the linux line.
Unmount the USB Drive (if mounted):
```
sudo umount <mount_point>
```
Boot from the USB Drive: Restart your computer and boot from the MiniOS USB drive.

Troubleshooting:

Kernel Panic: Kernel error. Possible causes: incompatible kernel, missing driver, or problem with initramfs. Try the old kernel and re-check the steps.
No Bootable Device: Check the bootloader configuration (syslinux.cfg and grub.cfg) and file locations.
Boots into Old Kernel: Check syslinux.cfg and grub.cfg.
Module Loading Errors: If MiniOS boots, but hardware doesn't work, a module might be missing. Ensure 01-kernel-<kernel-version>.sb is in place.

Summary of Files and Locations:

File	Source Location (after script)	Destination Location (booting from USB)	Destination Location (USB connected to another system)
`01-kernel-<kernel-version>.sb`	Current working directory	`/run/initramfs/memory/data/minios/`	`<mount_point>/minios/`
`vmlinuz-<kernel-version>`	Current working directory	`/run/initramfs/memory/data/minios/boot/`	`<mount_point>/minios/boot/`
`initrfs-<kernel-version>.img`	Current working directory	`/run/initramfs/memory/data/minios/boot/`	`<mount_point>/minios/boot/`
`syslinux.cfg`		`/run/initramfs/memory/data/minios/boot/syslinux.cfg`	`<mount_point>/minios/boot/syslinux.cfg`
`grub.cfg`		`/run/initramfs/memory/data/minios/boot/grub/grub.cfg`	`<mount_point>/minios/boot/grub/grub.cfg`