Switch to HWE kernel and improve boot reliability

- Install linux-image-generic-hwe-24.04 (6.14+) for RTL8125BP XID 689 support - Enable noble-updates and noble-security repositories in chroot - Add explicit rdinit=/init and panic=-1 kernel parameters for boot robustness - Rename CLAUDE.md to AGENTS.md for broader AI assistant coverage - Document dracut module alternative and verify-image.sh utility - Clean up initramfs netboot script comments
2026-02-01 15:51:19 +01:00
parent a9b18b5821
commit b7a52c0c37
5 changed files with 52 additions and 15 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1 @@
+CLAUDE.md
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,6 @@
-# CLAUDE.md
+# AGENTS.md

-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to AI coding assistants when working with code in this repository.

 ## Project Overview

@@ -69,6 +69,14 @@ Located in `initramfs/` directory, passed to `mkinitramfs` with `-d` flag:
  - Mounts squashfs read-only
  - If `overlayroot=tmpfs`, creates overlay with tmpfs upper layer for writes

+### Dracut Module (Alternative)
+
+Located in `dracut-module/90netboot/`, an alternative initramfs approach using dracut:
+
+- **module-setup.sh** - Dracut module setup and dependencies
+- **parse-netboot.sh** - Parses kernel command line for netboot parameters
+- **mount-netboot.sh** - Handles HTTP squashfs download and mounting
+
 ### iPXE Boot Configuration

 **http/boot.ipxe** - iPXE script that:
@@ -83,7 +91,7 @@ Located in `initramfs/` directory, passed to `mkinitramfs` with `-d` flag:

 Built systems are configured with:
 - Norwegian keyboard layout (nb_NO.UTF-8 + en_US.UTF-8 locales)
- Root SSH access with specific authorized keys (see build-image.sh:138-141)
+- Root SSH access with specific authorized keys (see build-image.sh around line 160)
 - Password auth disabled, pubkey only
 - Network via netplan with DHCP (systemd-networkd)
 - Ephemeral tmpfs mounts: /tmp (2G), /var/tmp (1G), /var/log (1G), /run (512M)
@@ -103,20 +111,36 @@ Built systems are configured with:
 - Skips full debootstrap/package installation
 - **Hardcoded paths:** `/srv/netboot/*` - update if repo moves

+**verify-image.sh** - Validate built image completeness
+- Checks all required files exist (vmlinuz, initrd, squashfs, boot.ipxe)
+- Validates file types (kernel, cpio archive, squashfs)
+- Verifies file permissions (644 for HTTP serving)
+- Inspects initramfs for custom netboot script and required binaries
+- Checks squashfs for critical directories and configurations
+- Validates iPXE configuration references correct files
+- Run with `./verify-image.sh` after `make build`
+
 ## File Structure

 ```
 .
 ├── build-image.sh          # Main build script
 ├── Makefile                # Build/deploy automation
-├── boot.ipxe               # iPXE boot configuration (in http/)
-├── initramfs/              # Custom initramfs configuration
+├── verify-image.sh         # Image validation script
+├── chroot-rootfs.sh        # Chroot helper (hardcoded paths)
+├── rebuild-squashfs.sh     # Rebuild helper (hardcoded paths)
+├── AGENTS.md               # AI assistant guidance (this file)
+├── CLAUDE.md               # Claude-specific guidance
+├── initramfs/              # Custom initramfs configuration (mkinitramfs)
 │   ├── initramfs.conf      # mkinitramfs config
 │   ├── modules             # Extra kernel modules
 │   ├── hooks/netboot       # Binary copying hook
 │   └── scripts/netboot     # HTTP root mounting logic
-├── chroot-rootfs.sh        # Chroot helper (hardcoded paths)
-├── rebuild-squashfs.sh     # Rebuild helper (hardcoded paths)
+├── dracut-module/          # Alternative initramfs (dracut)
+│   └── 90netboot/
+│       ├── module-setup.sh
+│       ├── parse-netboot.sh
+│       └── mount-netboot.sh
 ├── build/                  # Build artifacts (gitignored)
 │   └── rootfs/             # debootstrap rootfs
 ├── images/                 # Versioned builds (gitignored)
@@ -140,6 +164,6 @@ Built systems are configured with:
 - 15-30 minute build time
 - ~1GB disk space for build artifacts

-**SSH key management:** Root SSH keys are embedded in build-image.sh:138-141. Update these before building images for new environments.
+**SSH key management:** Root SSH keys are embedded in build-image.sh around line 160. Update these before building images for new environments.

 **Network driver:** RTL8125 (r8125) driver is explicitly loaded in initramfs for 2.5GbE NICs. If different NICs are used, update `initramfs/modules` and `initramfs/scripts/netboot`.
--- a/build-image.sh
+++ b/build-image.sh
@@ -53,13 +53,27 @@ echo "keyboard-configuration keyboard-configuration/variant select Norwegian" |
 echo "locales locales/default_environment_locale select en_US.UTF-8" | debconf-set-selections
 echo "locales locales/locales_to_be_generated multiselect en_US.UTF-8 UTF-8, nb_NO.UTF-8 UTF-8" | debconf-set-selections

-# Update and upgrade
+# Enable noble-updates and noble-security for HWE kernel
+cat > /etc/apt/sources.list.d/ubuntu.sources << 'SOURCES'
+Types: deb
+URIs: http://archive.ubuntu.com/ubuntu
+Suites: noble noble-updates noble-backports
+Components: main universe multiverse
+Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
+
+Types: deb
+URIs: http://security.ubuntu.com/ubuntu
+Suites: noble-security
+Components: main universe multiverse
+Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
+SOURCES
+
 apt-get update
 apt-get upgrade -y

-# Install essential packages
+# Install HWE kernel (6.14+) for RTL8125BP XID 689 support
 apt-get install -y \
-    linux-image-generic \
+    linux-image-generic-hwe-24.04 \
    linux-firmware \
    busybox-initramfs \
    initramfs-tools \
--- a/http/boot.ipxe
+++ b/http/boot.ipxe
@@ -5,6 +5,6 @@ kernel http://192.168.100.1:8800/vmlinuz
 echo Loading initramfs...
 initrd http://192.168.100.1:8800/initrd-netboot.img
 echo Setting kernel arguments for HTTP root mounting
-imgargs vmlinuz initrd=initrd-netboot.img boot=netboot root=http://192.168.100.1:8800/filesystem.squashfs rootfstype=squashfs overlayroot=tmpfs ip=dhcp console=tty0 console=ttyS0,115200 loglevel=7
+imgargs vmlinuz initrd=initrd-netboot.img rdinit=/init boot=netboot root=http://192.168.100.1:8800/filesystem.squashfs rootfstype=squashfs overlayroot=tmpfs ip=dhcp console=tty0 console=ttyS0,115200 loglevel=7 panic=-1
 echo Booting system...
 boot
--- a/initramfs/scripts/netboot
+++ b/initramfs/scripts/netboot
@@ -1,7 +1,5 @@
 #!/bin/sh
-
-# Import standard initramfs functions
-. /scripts/functions
+# Netboot HTTP root mounting - sourced by initramfs init (functions already loaded)

 export PATH=/usr/bin:/usr/sbin:/bin:/sbin
 MOUNTPOINT=/root