diff --git a/AGENTS.md b/AGENTS.md new file mode 120000 index 0000000..681311e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1 @@ +CLAUDE.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 8537895..36f237f 100644 --- 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`. diff --git a/build-image.sh b/build-image.sh index 9cc198f..38ef58c 100755 --- 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 \ diff --git a/http/boot.ipxe b/http/boot.ipxe index f594a4a..b55d2f4 100644 --- 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 diff --git a/initramfs/scripts/netboot b/initramfs/scripts/netboot index aea0870..c561892 100755 --- 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