How to Manually Merge SquashFS Files During GRUB Boot for Live Linux Distributions

Welcome to revWhiteShadow, your personal blog dedicated to exploring the intricate world of Linux and its boot processes. Today, we delve into a fascinating and often challenging aspect of customizing live Linux distributions: manually merging SquashFS files during boot directly from the GRUB command line. This process, while not for the faint of heart, offers unparalleled control and understanding of how live systems are assembled and initiated. We understand you’ve encountered the dreaded initramfs prompt and the frustrating “Unable to find a medium containing live file system” error. This guide aims to provide a comprehensive, step-by-step solution to conquer these challenges and achieve a successful boot.

Understanding the Live Boot Process and the Role of SquashFS

Before we dive into the manual merge, it’s crucial to grasp the fundamental architecture of a live Linux distribution. Unlike traditional installations where the root filesystem is directly written to a hard drive, live systems operate from an ephemeral environment. This environment is typically constructed in RAM, drawing its core components from a compressed read-only filesystem, most commonly a SquashFS archive.

When you boot a live Linux distro from a USB drive or an ISO image, GRUB (the GRand Unified Bootloader) plays a pivotal role. It’s responsible for loading the kernel (vmlinuz), the initial RAM disk (initrd), and eventually the root filesystem. For live systems, the “root filesystem” is not a traditional partition but rather the contents of the SquashFS file, which is then overlaid with a writable layer (often a tmpfs in RAM) to provide persistence and allow for temporary changes.

The initrd file acts as a miniature operating system itself. Its primary function is to prepare the environment for the main Linux kernel. This includes loading necessary modules, detecting hardware, and critically, finding and mounting the root filesystem. In the context of live systems, the initrd’s job is to locate the filesystem.squashfs file and prepare it for the kernel to utilize as the root directory.

You correctly observed that the casper folder often houses vmlinuz, initrd, and filesystem.squashfs. The term “casper” is indeed associated with Ubuntu’s live system infrastructure, often managing the persistence layer. However, for manual booting, the kernel itself doesn’t inherently need the casper folder name to be present in the boot parameters; rather, it needs to be told where to find the necessary files, including the filesystem.squashfs.

The core of your problem lies in the init process within the initrd failing to locate the filesystem.squashfs file. This can happen for several reasons:

Incorrect path specification: GRUB or the kernel command line might not be providing the initrd with the correct location of the filesystem.squashfs.
Missing kernel modules: The initrd might lack the necessary modules to interact with the storage device where the filesystem.squashfs resides.
Filesystem type issues: The initrd might not be configured to recognize the filesystem on the bootable media.
Union filesystem setup failure: The initrd’s script responsible for setting up the union filesystem (like UnionFS or OverlayFS) fails because it cannot find the filesystem.squashfs as a source.

Your observation about the root= parameter being device-specific and not path-specific in GRUB is generally accurate. GRUB itself is responsible for making a partition accessible. The kernel then takes over and needs to understand how to access files within that partition.

GRUB Boot Entry Fundamentals for Live Systems

To effectively instruct GRUB, we need to construct a precise boot entry in your grub.cfg or equivalent. This entry dictates what GRUB should load and how it should be passed to the kernel.

A typical GRUB boot entry for a live system will look something like this:

menuentry "My Custom Live Boot" {
    set root='(hd0,msdos2)'  # Example: First hard drive, second partition
    linux /casper/vmlinuz boot=casper quiet splash ---
    initrd /casper/initrd
}

Let’s break down the key components you’ll need to manipulate:

set root='(hdX,msdosY)' or set root='(hdX,gptY)': This directive tells GRUB which device and partition contains your live system files. hdX refers to the hard drive number (0 for the first, 1 for the second, etc.), and msdosY or gptY refers to the partition number. You’ll need to identify the correct partition.
linux /casper/vmlinuz: This specifies the kernel image to load. The path is relative to the root device you set.
boot=casper: This is a kernel parameter passed to the initrd and subsequently the kernel. It tells the live system’s boot scripts that it’s a Casper-based live system.
quiet splash: These are common parameters to reduce boot verbosity. You might want to remove quiet initially to see more diagnostic messages.
---: This is a separator that signifies the end of the kernel command line arguments and the beginning of the initrd file.
initrd /casper/initrd: This specifies the initial RAM disk image.

Diagnosing and Resolving the “Unable to find a medium” Error

The error message “Unable to find a medium containing live file system” is a clear indicator that the initrd has successfully booted but failed to locate and mount the filesystem.squashfs. Your recent attempts to add root=UUID= were a step in the right direction, as this parameter is crucial for the kernel to identify the root partition. However, the root= parameter, when referring to a block device, is typically used for persistent installations where the kernel directly mounts the root filesystem. For live systems, the initrd often uses different mechanisms to locate the SquashFS.

Let’s refine your approach. The key is to ensure the initrd’s scripts know where to find filesystem.squashfs.

Identifying the Correct Partition for Your Live System

First and foremost, you need to accurately identify the partition containing your live Linux distro files. When GRUB boots, it presents you with a prompt or a menu. At the GRUB prompt, you can use commands to inspect your disks and partitions:

ls: This command lists devices and partitions accessible by GRUB. You’ll see output like (hd0), (hd0,msdos1), (hd0,msdos2), etc.
ls (hd0,msdos2)/: If you suspect the files are on the second partition of the first drive, this command will list the contents of that partition. Look for the casper folder or the presence of vmlinuz, initrd, and filesystem.squashfs directly.

Once you’ve identified the correct partition, you’ll set it in your GRUB entry:

set root='(hdX,msdosY)'

Replace (hdX,msdosY) with the correct partition identifier you discovered.

Correcting Kernel Parameters for SquashFS Location

The boot=casper parameter is a hint to the live system’s init scripts. However, these scripts themselves need to know where to look for the filesystem.squashfs. The most common way to achieve this is by specifying the device or partition containing the live media using a parameter that the initrd scripts understand.

Historically, parameters like toram or specific boot options related to the live system’s builder (e.g., fromiso, union) have been used. For many Debian/Ubuntu-based live systems, the findiso kernel parameter can be instrumental. This parameter tells the initrd to search for an ISO image or, in some cases, a specific filesystem structure on a given partition.

Let’s try modifying your GRUB entry to explicitly tell the system where the live files reside:

Scenario 1: SquashFS is directly on the boot partition, inside a folder named casper

If your filesystem.squashfs is indeed within a casper folder on the partition you’ve identified, the initrd needs to be aware of this. The boot=casper parameter is a good start, but we might need to guide it further.

Consider this GRUB entry:

menuentry "Custom Live Boot - Enhanced SquashFS Path" {
    set root='(hdX,msdosY)'  # Replace with your identified partition
    linux /casper/vmlinuz boot=casper toram findiso=/casper/filesystem.squashfs quiet splash ---
    initrd /casper/initrd
}

Explanation of Changes:

toram: This parameter instructs the system to load the entire live filesystem into RAM. This is often necessary for the union filesystem to work seamlessly, as it performs better when the base image is in RAM.
findiso=/casper/filesystem.squashfs: This is a crucial parameter for many live systems. It tells the initrd to look for a file named filesystem.squashfs within a casper directory on the detected boot media. Even though you’re not booting from an ISO directly, the findiso mechanism can often locate files on a partition structured similarly.

Important Note on findiso: The exact behavior and support for findiso can vary depending on the specific live system build and the version of initramfs-tools or equivalent used. You might need to experiment with slightly different parameter names or structures.

Scenario 2: SquashFS is directly on the boot partition (no casper folder)

If you’ve placed vmlinuz, initrd, and filesystem.squashfs directly on the root of your boot partition (e.g., /vmlinuz, /initrd, /filesystem.squashfs), you’ll need to adjust the paths accordingly.

menuentry "Custom Live Boot - Direct File Paths" {
    set root='(hdX,msdosY)'  # Replace with your identified partition
    linux /vmlinuz boot=live union=overlay quiet splash ---
    initrd /initrd
}

In this case, the boot=live parameter is a more generic indicator of a live system. The union=overlay parameter explicitly tells the initrd to use the overlay filesystem for the union mount, which is the modern standard.

The challenge here is that without a casper folder, the initrd’s default scripts might not have a specific parameter to find filesystem.squashfs directly at the root. You might need to pass a parameter that specifies the root filesystem device more directly, or a custom parameter that your initrd’s scripts are designed to interpret.

The Role of `root=` with UUID

You mentioned adding root=UUID=.... While root= is typically for persistent installs, in some advanced initrd configurations, it can be used to hint at the device where the live filesystem is located. However, it’s usually not sufficient on its own to point to a SquashFS file.

The initrd needs to execute a script that:

Mounts the partition identified by root='(hdX,msdosY)' or the partition containing the findiso target.
Locates the filesystem.squashfs file on that mounted partition.
Mounts the filesystem.squashfs as a read-only filesystem.
Sets up a union filesystem (e.g., OverlayFS) using the mounted SquashFS as the lower layer and a RAM-based writable layer as the upper layer.
Pivots into this union filesystem, making it the new root filesystem.

Your initrd might not be finding the filesystem.squashfs because the default scripts look for it in specific locations or via specific parameters that are not being provided correctly.

Customizing the Initramfs (Advanced)

If the standard kernel parameters are not working, it might be necessary to understand how the initrd for your specific distribution is structured and how it searches for the SquashFS. This often involves unpacking the initrd file itself (which is usually a gzipped cpio archive) and examining the scripts within it.

You can unpack an initrd like this:

Copy the initrd:
```
cp /casper/initrd /tmp/initrd.gz
```

Uncompress and extract:

cd /tmp
gunzip initrd.gz
cpio -idmv < initrd

Inside the /tmp directory, you’ll find the initrd’s contents. Look for scripts in directories like init, init.d, or specific directories related to live booting. You’re particularly interested in scripts that handle mounting filesystems, detecting boot media, and setting up the union filesystem.

Within these scripts, you’ll likely find logic that searches for filesystem.squashfs. This search might be hardcoded to look for it relative to the boot device, or it might look for a specific kernel parameter.

Adding a Custom Parameter:

If you find a script that uses a custom parameter to specify the location of the SquashFS, you can add this to your GRUB entry. For instance, if the script looks for a parameter like squashfs_path=/casper/filesystem.squashfs, your GRUB entry would become:

menuentry "Custom Live Boot - Custom SquashFS Path Param" {
    set root='(hdX,msdosY)'  # Replace with your identified partition
    linux /casper/vmlinuz boot=casper squashfs_path=/casper/filesystem.squashfs quiet splash ---
    initrd /casper/initrd
}

Searching for the filesystem.squashfs within the Initramfs:

You mentioned running grep -rnw 'initrd file loop mounted location' -e 'filesystem.squashfs'. While grep is excellent for searching within files, the initrd isn’t “mounted” in a traditional sense before the scripts inside it run. The scripts themselves perform the mounting.

A more effective way to find out how the initrd is trying to locate the SquashFS is by examining the scripts within the unpacked initrd. You’d look for patterns like:

mount -o ro,loop ... filesystem.squashfs
findfs ... filesystem.squashfs
losetup ... filesystem.squashfs
Parameters like rootfstype=squashfs or specific union filesystem setup commands.

The `root=` Parameter and OverlayFS

Let’s revisit your root=UUID=... attempt. When using OverlayFS, the kernel command line might look like:

root=/dev/mapper/live-root ... rootfstype=overlayfs overlay.lowerdir=/rofs,overlay.upperdir=/rwfs,overlay.workdir=/work

Here, /rofs would be the mount point for your read-only SquashFS, and /rwfs would be the RAM-based writable layer. The initrd is responsible for setting this up. The challenge is that the initrd needs to know where to find /rofs (i.e., the SquashFS).

If your initrd is designed to use the root= parameter to identify the device containing the live filesystem, and then internally looks for filesystem.squashfs on that device, your root=UUID=... might have been conceptually correct but perhaps combined with other missing parameters or incorrect paths.

Troubleshooting GRUB Configuration

Correct Partition: Double-check your set root='(hdX,msdosY)'. Even a small typo can lead to GRUB not finding the files.
File Paths: Ensure the paths to vmlinuz and initrd are correct relative to the set root device.
Kernel Parameters: Experiment with removing quiet and splash to see more detailed boot messages. This is invaluable for diagnosing where the process fails.
GRUB Version: While most modern GRUB versions are similar, very old or very new versions might have subtle differences in how they handle certain commands.

Constructing the Definitive GRUB Entry

Based on your description and common live boot practices, let’s try to construct a robust GRUB entry. We’ll assume your live system files (vmlinuz, initrd, filesystem.squashfs) are in a casper directory on the second partition of your first hard drive.

Step 1: Identify your boot partition. Boot your computer, and when you see the GRUB menu or prompt, press c to enter the command line. Type ls and press Enter. Note the output, which might look like:

(hd0) (hd0,msdos1) (hd0,msdos2) (hd0,msdos3) ...

Now, try ls (hd0,msdos2)/casper/ (replace msdos2 with the partition you suspect). If you see vmlinuz, initrd, and filesystem.squashfs, then (hd0,msdos2) is your target.

Step 2: Create or edit your GRUB configuration. If you’re using a custom GRUB configuration file (e.g., grub.cfg in /boot/grub/ or a custom file you’ve chained loaded), add the following entry:

menuentry "Advanced Live Boot - SquashFS Merge" {
    # Set the root device to the partition containing your live distro files.
    # Replace (hd0,msdos2) with your actual partition identifier.
    set root='(hd0,msdos2)'

    # Load the kernel. 'boot=casper' is typical for Ubuntu-based distros.
    # 'toram' loads the entire filesystem into RAM, often required for UnionFS.
    # 'findiso=...' helps the initrd locate the squashfs.
    # Remove 'quiet' to see detailed boot messages for troubleshooting.
    linux /casper/vmlinuz boot=casper toram findiso=/casper/filesystem.squashfs rootdelay=5 ro ---

    # Load the initial RAM disk.
    initrd /casper/initrd
}

Explanation of Key Parameters in this Definitive Entry:

set root='(hd0,msdos2)': Crucial for GRUB to locate files. Ensure this is the correct partition.
linux /casper/vmlinuz: Specifies the kernel executable. Path is relative to set root.
boot=casper: Informs the initrd scripts that this is a Casper live system.
toram: Loads the entire SquashFS into RAM. This is vital for the union filesystem to function correctly and efficiently, as it avoids disk I/O issues.
findiso=/casper/filesystem.squashfs: Instructs the initrd’s boot scripts to search for the filesystem.squashfs file within the casper directory on the detected boot media. This is often the missing piece that allows the system to find your compressed root filesystem.
rootdelay=5: Adds a 5-second delay before the kernel tries to access the root device. This can be helpful on systems where the storage device takes a moment to become fully available.
ro: Sets the root filesystem as read-only initially, which is standard for live systems before the union overlay is established.
---: Separator between kernel parameters and the initrd file.
initrd /casper/initrd: Loads the initial RAM disk. Path is relative to set root.

Why this approach is likely to succeed:

This combination of parameters is designed to overcome the common pitfalls:

GRUB correctly identifies the partition using set root.
The kernel is loaded with the correct path.
The initrd is loaded.
The initrd’s scripts are given explicit instructions via boot=casper and findiso=/casper/filesystem.squashfs to locate your SquashFS file.
toram ensures the SquashFS is readily available in memory for the union filesystem setup.
rootdelay can prevent timing issues.

By providing these specific instructions, you are effectively guiding the initrd through the process of finding, mounting, and integrating your filesystem.squashfs into the live environment, thus resolving the “Unable to find a medium containing live file system” error.

Remember to replace (hd0,msdos2) with your actual partition. If findiso doesn’t work as expected, you may need to delve deeper into the initrd scripts for your specific distribution to understand its preferred method of locating the SquashFS. However, this comprehensive GRUB entry is the most robust starting point for manual live booting.

How to merge squashfs file during booting of ’live’ linux distros from GRUB manually?

How to Manually Merge SquashFS Files During GRUB Boot for Live Linux Distributions #

Understanding the Live Boot Process and the Role of SquashFS #

GRUB Boot Entry Fundamentals for Live Systems #

Diagnosing and Resolving the “Unable to find a medium” Error #

Identifying the Correct Partition for Your Live System #

Correcting Kernel Parameters for SquashFS Location #

The Role of root= with UUID #

Customizing the Initramfs (Advanced) #

The root= Parameter and OverlayFS #

Troubleshooting GRUB Configuration #

Constructing the Definitive GRUB Entry #