#3614 PR `merged`: Add REAR_INITRD_OVERLAY to split initramfs into core + SquashFS overlay¶

Labels: enhancement, fixed / solved / done, severe improvement

rmetrich opened issue at 2026-07-03 07:48:¶

Summary¶

On systems where the initramfs is very large (e.g. 559 MiB on RHEL 10 due to firmware and kernel modules), some hardware or bootloader configurations fail to load it into memory. This new opt-in feature (REAR_INITRD_OVERLAY) splits the recovery system into a small initramfs and a SquashFS overlay image, reducing the initramfs from ~559 MiB to ~100 MiB.

How it works¶

Build time (pack stage): firmware and non-essential kernel modules are moved from the rootfs into a SquashFS image. Module dependencies and required firmware files are auto-detected and kept in the initramfs.
Boot time: a new early startup script (02-mount-rear-overlay.sh) starts udev to auto-detect hardware and load drivers from the initramfs, then locates and mounts the overlay (from ISO, USB, PXE server, or local /boot), applies it, and retrigggers udev with the full module set.

Supported output methods¶

Output	Overlay delivery	Essential modules kept
ISO	SquashFS on ISO filesystem	Storage, CD/DVD, USB drivers
USB	SquashFS on USB ext3/ext4 partition	Storage, USB drivers, ext4
PXE	Downloaded via `curl` from TFTP/HTTP	Network drivers
GRUB_RESCUE	Copied to `/boot`, path via kernel cmdline	/boot filesystem + storage driver (auto-detected)

Apply modes¶

copy: overlay content is extracted into tmpfs at boot. Simple, robust, ISO/USB can be ejected after boot.
mount: overlay stays mounted via overlayfs on /usr/lib/firmware and /usr/lib/modules. Saves RAM but source device must stay accessible.

MODULES integration¶

MODULES=('all_modules') (default): entire driver categories are kept in the initramfs using a directory-based approach.
Restricted MODULES (loaded_modules, empty, explicit list): only loaded modules plus overlay-access essentials (loop, squashfs, isofs, etc.) are kept. Avoids including unneeded drivers.

Additional features¶

Module dependency resolution: modprobe --show-depends is used at build time to pull missing dependencies into the initramfs.
Firmware auto-detection: modinfo -F firmware detects firmware files required by essential modules (supports .xz/.zst compressed firmware).
REAR_INITRD_FIRMWARE_FILES: array variable to manually specify additional firmware patterns for drivers that don't properly declare their firmware requirements.
s390 support: on Linux-s390, the entire kernel/drivers/s390 tree is kept (cio bus layer + block/scsi/net/crypto).

Configuration¶

# In /etc/rear/local.conf:
REAR_INITRD_OVERLAY=copy    # or "mount"

# Optional: manually add firmware for drivers that don't declare dependencies
REAR_INITRD_FIRMWARE_FILES=( 'bnx2/*' 'tigon/*' )

Requires squashfs-tools package (mksquashfs) on the build system. PXE also requires curl.

Example output¶

Creating recovery system overlay (rootfs is 700 MiB before split)
Moving firmware files (404 MiB) to overlay
Pulled 21 module dependencies into initramfs
Kept 37 MiB of essential kernel modules in initramfs (was 102 MiB)
Kept 57 firmware files required by essential modules
Created rear-overlay.sqsh (438 MiB) in 29 seconds
Rootfs reduced from 700 MiB to 227 MiB
Created initrd.cgz with gzip default compression (105 MiB) in 8 seconds

New files¶

File	Purpose
`prep/default/395_include_overlay_tools.sh`	Adds `depmod`/`curl` to PROGS, overlay modules to MODULES_LOAD, detects /boot for GRUB_RESCUE
`pack/GNU/Linux/500_create_rear_overlay.sh`	Splits rootfs into initramfs + SquashFS overlay with dependency/firmware resolution
`skel/default/etc/scripts/system-setup.d/02-mount-rear-overlay.sh`	Boot-time script: udev hw detection, overlay mount, content application, udev retrigger

Modified files¶

File	Change
`conf/default.conf`	`REAR_INITRD_OVERLAY` and `REAR_INITRD_FIRMWARE_FILES` variables
`output/ISO/Linux-i386/800_create_isofs.sh`	Copy overlay squashfs to ISO
`output/PXE/default/800_copy_to_tftp.sh`	Copy overlay to TFTP server
`output/PXE/default/801_copy_to_http.sh`	Copy overlay to HTTP server
`output/PXE/default/810_create_pxelinux_cfg.sh`	`rear_overlay=` in kernel cmdline
`output/USB/default/830_copy_kernel_initrd.sh`	Copy overlay to USB device
`output/default/940_grub2_rescue.sh`	Copy overlay to /boot, `rear_overlay=` in Grub entry
`lib/bootloader-functions.sh`	`rear_overlay=` in PXE boot menu entries

Test plan¶

Tested on RHEL 10.2 (BIOS and UEFI VMs):

☒ ISO without overlay (regression: no interference)
☒ ISO copy mode, default MODULES
☒ ISO copy mode, MODULES=() (restricted)
☒ ISO mount mode
☒ USB copy mode
☒ USB mount mode, MODULES=()
☒ PXE copy mode
☒ PXE mount mode
☒ GRUB_RESCUE with overlay (BIOS)
☒ UEFI ISO copy mode
☒ UEFI ISO mount mode

codacy-production commented at 2026-07-03 07:50:¶

Up to standards ✅¶

🟢 Issues 0 issues

>
> > **Results:** > `0` new issues > > [View in > Codacy](https://app.codacy.com/gh/rear/rear/pull-requests/3614/issues) >

_{NEW Get contextual insights on your PRs based on Codacy's
metrics, along with PR and Jira context, without leaving GitHub. Enable
AI
reviewer}
_{TIP This summary will be updated as you push new changes.}

jsmeix commented at 2026-07-03 08:52:¶

@rmetrich
WOW!
Thank you for this big enhancement.
When the initrd is too big it was a dead end for the user.
Now there is a way out.

rmetrich commented at 2026-07-06 14:50:¶

I'm putting back as Draft because I need quite a lot of fixes

gdha commented at 2026-07-09 08:25:¶

@rmetrich Thank you - this is a serious improvement!

jsmeix commented at 2026-07-10 11:56:¶

@rear/contributors
please review it - as time permits.

jsmeix commented at 2026-07-20 14:03:¶

@rear/contributors
I would like to merge it on Wednesday (22. July) afternoon
unless there are questions or objections.

schlomo commented at 2026-07-23 12:11:¶

@rmetrich thanks a lot for this enhancement. I can imagine that we'd like to extend it to cover other large software packages too, for example heavy backup software. Not needed for booting, can be loaded as a second stage.

Thanks a lot!

rmetrich commented at 2026-07-23 12:17:¶

@rmetrich thanks a lot for this enhancement. I can imagine that we'd like to extend it to cover other large software packages too, for example heavy backup software. Not needed for booting, can be loaded as a second stage.

Thanks a lot!

Indeed that could also be an improvement.

[Export of Github issue for rear/rear.]

#3614 PR merged: Add REAR_INITRD_OVERLAY to split initramfs into core + SquashFS overlay¶